EMsoftOO (version 6.0 of EMsoft)

This repository contains the source code for version 6.0 of the EMsoft package; the main difference between EMsoft 5.0 (https://github.com/EMsoft-org/EMsoft) and the present repository is the fact that EMsoftOO is entirely written in Object Oriented fortran-2018 (hence the letters "OO" at the end of EMsoftOO). This is a complete rewrite of the original package and is mostly backwards compatible with version 5.0 in terms of the data files that are generated by various programs. Most of the changes are "under the hood" and not really visible to the ordinary user (except perhaps that most of the programs appear to execute more quickly than those in version 5.0).

EMsoftOO Version 6.0 should be considered a beta version; the code is still very much under development, and not all of the version 5.0 programs have been ported yet. Nevertheless, most of the SEM-related code has been converted and tested. We are in the process of updating the wiki pages.

This release of EMsoftOO requires an updated Software Developer Toolkit (SDK); please go to this page and follow the instructions to install a new SDK before you attempt to build the present release.

New in this Release !!

There is now a lightweight graphical user interface, written in python, that allows the user to load any of the namelist template files, edit it with the proper parameters, save the file to the correct working directory, and then execute the program. The usual command line output is displayed in a separate region of the GUI and can be saved to a log file. This is a very early implementation of what will likely become a more powerful user interface. The nml_editor.py is located in the Source/pyEMsoftOO/emsoft folder and requires a standard python environment like miniconda.

Apple Metal GPU backend (macOS)

Apple has deprecated OpenCL and no longer supports it natively on Apple Silicon (M-series) hardware. EMsoftOO now includes a native Apple Metal GPU backend so that the GPU-accelerated programs continue to work — and run faster — on modern Macs. All of the GPU compute kernels that are actually used by the package (the Monte Carlo electron-trajectory kernels behind EMMCOpenCL, including the foil and interaction-volume modes, and the dictionary-indexing inner-product kernel used by EMDI) have been translated to the Metal Shading Language; on Apple Silicon the Metal versions typically run about twice as fast as the old OpenCL path, thanks to Metal's native compiler and the unified-memory architecture.

The migration is transparent: the same programs are used in exactly the same way, with the same namelist files and the same output. The Metal backend is a drop-in replacement for the OpenCL one, selected at build time, so no source code in the individual programs changed.

A few practical notes:

• It is on by default on macOS. On Apple builds, EMsoftOO_ENABLE_Metal_SUPPORT defaults to ON and the Metal backend is used in place of OpenCL. To force the OpenCL backend instead, configure with -DEMsoftOO_ENABLE_Metal_SUPPORT=OFF. On non-Apple platforms the option is always off and OpenCL is used as before.
• No extra library to install. Apple's metal-cpp headers are vendored inside the repository (ExternalProjects/metal-cpp), and the Metal/Foundation frameworks ship with macOS, so nothing additional needs to be installed for the build to find them.
• The Metal shader compiler is required to build the kernels. The *.metal kernels are compiled to .metallib files at build time using xcrun metal, which is part of a full Xcode installation (and, on Xcode 16 and later, the separately-downloaded Metal Toolchain component). It is not included in the Command-Line-Tools-only install. If the Metal compiler is not found at configure time, EMsoftOO automatically falls back to the OpenCL backend (with a warning) rather than failing the build, so a clean default build still works on any Mac.

This is a beta feature; the Monte Carlo and dictionary-indexing paths have been validated against the OpenCL results, and further GPU programs are being verified.

Financial Support

EBSD/ECP/EKP development of this package, including dictionary indexing for EBSD/ECP, was started with support from an AFOSR/MURI grant, FA9550-12-1-0458; the original EBSD code from CTEMsoft 2.0 was developed with support from an ONR grant, N00014-12-1-0075. All recent development of EMsoft was performed with support from an ONR Vannevar Bush Faculty Fellowship, N00014-­16-­1-­2821, and an NSF research program DMR #1904629. Current development is carried out with support from NSF grant DMR-2203378. MDG would also like to acknowledge support from the John and Claire Bertucci Distinguished Professorship in Engineering.

Current and Past Contributors

EMsoft started as a source code base used for the creation of all figures in the Introduction to Conventional Transmission Electron Microscopy text book (Cambridge University Press, 2003, ISBN 0521629950) by M. De Graef. It has since grown into an open source project that has had many contributors and testers over the past nearly 20 years (in no particular order):

• Patrick Callahan
• Saransh Singh
• Stuart Wright
• Elena Pascal
• Will Lenthe
• Chaoyi Zhu
• Clément Lafond
• Joseph Tessmer
• Claude Code
• Ke-Wei Jin
• Michael Atkinson
• Joao Fonseca
• Michael Jackson
• Joey Kleingers
• Håkon Wiik Ånes
• McLean Echlin
• Zachary Varley

Installation

If you want to build EMsoftOO yourself, it would make sense to first get a GitHub account, and fork this repository into your account. Then clone the repo from your account onto your local computer. Before you can compile things, you need to first build the Software Developer Kit (EMsoftOO_SDK), which you can find here; follow the instructions for your platform to install the SDK. In addition, you will need to clone the EMsoftData repository, also from EMsoft-org, in a folder at the same level as the main repository folder.

Then, starting in the top folder where you have cloned the EMsoftOO repository, carry out the following commands for your platform.

For UNIX-type builds:

  mkdir EMsoftOOBuild
  cd EMsoftOOBuild
  mkdir Release
  cd Release
  cmake -DCMAKE_BUILD_TYPE=Release -DEMsoftOO_SDK=/somepath/EMsoftOO_SDK ../../EMsoftOO
  make -j
  cd ../
  mkdir Debug
  cd Debug
  cmake -DCMAKE_BUILD_TYPE=Debug -DEMsoftOO_SDK=/somepath/EMsoftOO_SDK ../../EMsoftOO
  make -j

For Windows 11 builds with the Intel oneAPI ifx compiler and Visual Studio 2022, use a fresh build folder from a cmd.exe session after loading the Intel/VS2022 toolchain. The /Z7 debug-info flags below are important on some systems where /Zi can fail during CMake compiler checks with fatal error C1041:

  call "C:\Program Files (x86)\Intel\oneAPI\setvars.bat" intel64 vs2022
  set "SDK_ROOT=C:/somepath/EMsoftOO_SDK"

  cmake -S . -B build-ifx-release -G "NMake Makefiles" ^
    -DBUILD_SHARED_LIBS=ON ^
    -DCMAKE_BUILD_TYPE=Release ^
    -DCMAKE_Fortran_COMPILER=ifx ^
    -DCMAKE_C_FLAGS_DEBUG:STRING="/MDd /Z7 /Ob0 /Od /RTC1" ^
    -DCMAKE_CXX_FLAGS_DEBUG:STRING="/MDd /Z7 /Ob0 /Od /RTC1" ^
    -DEMsoftOO_SDK=%SDK_ROOT% ^
    -DEMsoftOO_ENABLE_TESTING=OFF

  cmake --build build-ifx-release

Note that somepath should be replaced with wherever you installed the SDK. The UNIX commands above compile both a Release and a Debug version of EMsoftOO; the Windows 11 example shows a clean Release build tree. If you also need a Debug tree on Windows, repeat the same configure/build sequence with a different build folder name and -DCMAKE_BUILD_TYPE=Debug. If you are building with the classic Intel compiler rather than ifx, use jsonfortran-intel_DIR instead of jsonfortran-intelllvm_DIR. You can then add the path to the EMsoftOOBuild/Release/Bin folder or the Windows build Bin folder to your shell path and start using the programs. Note that the Debug version of the executables will run much more slowly than the Release version, but, if something goes wrong during the run, the error message of the Debug version will nearly always be more informative than for the Release version.

To always maintain an up-to-date version of the package, you may want to create a little script that will help you synchronize the repositories and compile in one step. Here is an example shell script for UNIX-flavored systems; the assumptions are that the EMsoftOO repository has been cloned into the folder EMsoftOOPublic, and the EMsoftData repository into EMsoftData:

cd EMsoftData
git pull --rebase origin develop
cd ../EMsoftOOPublic
git pull --rebase origin develop
cd ../EMsoftOOBuild
make -j

If you do not need the complete EMsoftOO package, you can compile sections of the package (e.g., SEM modalities only) by setting CMake switches using the ccmake GUI program, as described in the ccmake-options.md file.

Licenses

The BSD-3 license text below can be found at the start of every source file in the EMsoftOO package.

!###################################################################
! Copyright (c) 2013-2025, Marc De Graef Research Group/Carnegie Mellon University
! All rights reserved.
!
! Redistribution and use in source and binary forms, with or without modification, are 
! permitted provided that the following conditions are met:
!
!     - Redistributions of source code must retain the above copyright notice, this list 
!        of conditions and the following disclaimer.
!     - Redistributions in binary form must reproduce the above copyright notice, this 
!        list of conditions and the following disclaimer in the documentation and/or 
!        other materials provided with the distribution.
!     - Neither the names of Marc De Graef, Carnegie Mellon University nor the names 
!        of its contributors may be used to endorse or promote products derived from 
!        this software without specific prior written permission.
!
! THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
! AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
! ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 
! LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
! DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
! SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
! CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 
! OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE 
! USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
! ###################################################################