- Introduction
- Dependencies
- Features
- Building
- Running
- Planned Features
- Author
- Acknowledgements
- License
This is AMCSET, a materials ion bombardment simulation program with capabilities for electron bombardment simulation. It is written in C++ using the GNU standard libraries. Originally conceived of and written by Dr. Lin Shao, this is a program written to implement the methods used by Dr. Shao to efficiently perform electron bombardment calculations efficiently, a traditionally computationally expensive and slow task.
Having the ability to simulate electron and ion bombardment is an invaluable tool in the field of materials science, as it enables the prediction of irradiation penetration depth, allowing researchers to correlate experimental data with simulated data.
This is a program for simulating ion bombardment in materials. It can be used for simulating electron bombardment.
Written in C++, it is a highly optimized program, which takes full advantage of multi-threading, combined with performance-oriented programming to achieve extremely high performance calculations of both ion bombardment and electron bombardment.
Thanks to multi-threading support, thousands of simulations can be run in parallel and the performance can be tuned by setting the number of allowed threads in the settings.
Just like the classic SRIM program, this simulation can simulate the Stopping and Range of Ions in Matter. Using the settings.txt file, set any bombardment ion mass and Z-number, as well as any substrate mass and Z-number, and the program will simulate ion bombardment, outputting to a file with a name specified in the settings.
In addition to ion bombardment, this program can also simulate electron bombardment at high throughput. Through highly optimized Mott scattering calculations, a single electron bombardment can be completed in a fraction of a second, while this calculation would take several seconds or even minutes using traditional techniques.
This works by calculating the total Mott scattering cross-section for a group of many local substrate atom interactions, with the assumption that elastic energy loss is negligible over small distances. This assumption is demonstrated to be valid for groupings of up to local 1000 interactions.
This program employs multi-threading, which allows for multiple CPU cores to be employed generating bombardment data. Since each bombardment is independent, a separate thread can simulate an entire bombardment and write the simulation data to a file. This can be done with many threads simultaneously.
The program has a built-in protection which ensures that data from previous runs is not accidentally overridden. When the program encounters a file that has the same name as the name specified in the settings file, it checks to see if it has a file marker at the end (this marker can also be customized). If a marker is present, the old file is renamed <filename>_<Day>_<Month>_<Date>_<Hour>_<Minute>_<Second>_.<file extension>. For example, coordinateOutput.csv will become coordinateOutput_Thu_Mar_14_19-40-03_2024.csv if it is already present in the output directory when a new run is initiated.
There are several toggles available in the settings file that enables a user to select what data is reported by AMCSET. This is a valuable feature, as AMCSET can generate gigabytes of data if all the generated data is reported. Three toggles allow for reduction of output file size:
- logStoppingPointOnly - This option only logs the final resting point of each particle, and does not record the path that the particle took to get to the stopping point.
- logEndOfFlyingDistance (Electron only) This option reduces the number of coordinates logged by not logging every coordinate within a local substrate interaction group, but only logging the last interaction within a group. This can reduce the data size by a factor of
The data output from this program needs to be validated.
Building the program requires the C++ standard libraries, as well as a C++ compiler. This program was developed using the g++ and clang compiler. The compiler can be chosen by setting the -DCOMPILER flag when using cmake. On Linux, a C++ compiler and the associated standard libraries generally included with most distributions. This compiler is called g++, and it is all you will need to build and run this project.
This project uses Google gtest to handle test cases. The cmake configuration file automatically handles the installation of this dependency. If you encounter any gtest related issues on your system, ensure that it is installed using
sudo apt-get install libgtest-devThe testing environment has been configured, but no tests have been run so far. To run the "Trivial test"
Three compilers are supported, g++, clang++, and icpx (Intel compiler).
- There is currently a linker error generated when trying to compile with clang. Please build with ipcx or g++.
IMPORTANT: Please follow the build directions exactly to ensure successful compilation of the project. It is recoomended to copy and paste the instructions exactly
Note: This is a much more complicated process than building on Linux. It is recommended to install WSL2 (Windows Subshell for Linux) and cross-compile for Windows.
Work in progress This requires development using Microsoft Visual Studio, and the project has not yet been tested using it.
*Note: You can build and run this program on Windows using Windows Subshell for Linux (WSL). Go to https://learn.microsoft.com/en-us/windows/wsl/install to learn how to install WSL before moving forward.
Install the latest version of cmake. Do not use the version that is currently installed on your system. It is likely not recent enough. Either visit the CMake website or run the following:
cd ~
wget https://github.com/Kitware/CMake/releases/download/v3.29.0-rc4/cmake-3.29.0-rc4-linux-x86_64.sh
chmod u+x cmake-3.29.0-rc4-linux-x86_64.sh
./cmake-3.29.0-rc4-linux-x86_64.shScroll down and press "y" and Enter to accept the license agreement. Then press "y" to allow the installation script to make a subdirectory for your CMake installation.
Please build this project using a Linux. If you are on Windows, install WSL2 before continuing. Support for building on Windows is planned for future releases.
This project can be built using cmake. Once you clone the repository to your local machine, ensure you have cmake installed. If you are on a Debian Linux distribution, you can do this using
sudo apt install cmakeIf you are using another Linux distribution or Windows, ensure you have cmake, a C++ compiler, and the C++ standard libraries installed on your system before continuing.
Note that Windows is not officially supported, but it is not expected that this code would not compile and run on Windows.
To build the project, first nagivate to the build directory:
cd buildThen configure cmake
cmake ..You should see an output like this
-- The CXX compiler identification is GNU XX.X.X
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Check for working CXX compiler: /usr/bin/c++ - skipped
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- The C compiler identification is GNU XX.X.X
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Check for working C compiler: /usr/bin/gcc - skipped
-- Detecting C compile features
-- Detecting C compile features - done
-- Found Python3: /usr/bin/python3.XX (found version "3.XX.XX") found components: Interpreter
-- Performing Test CMAKE_HAVE_LIBC_PTHREAD
-- Performing Test CMAKE_HAVE_LIBC_PTHREAD - Success
-- Found Threads: TRUE
-- Using /usr/bin/gcc C compiler
-- Using /usr/bin/c++ C++ compiler
-- Production mode is enabled.
-- Configuring done (2.5s)
-- Generating done (0.0s)
-- Build files have been written to: /path/to/project/AMCSET/buildYou can also set flags to configure cmake to use a different compiler. Read the CMakeLists.txt file to learn more.
Once cmake is configured, build the project using
cmake --build .This will build the project and place the binary in the [/bin] folder.
Test cases can be found in the tests directory. To run the all the test suites, run
ctestonce you've built the project.
Run the program using the following command
./bin/AMCSETBy default, the program does not produce any output, it simply reads the settings.txt file and completes a simulation based on those settings before exiting.
AMCSET supports a number of command-line arguments. You can see all the available arguments using the -h flag
./bin/AMCSET -hIf you wish to clear the build directory and associated files, run
make cleanThis will automatically delete any executables and intermediate files generated by the build process.
By default, the program outputs a .csv file. The name and file extension can be changed in the settings.txt file.
The output has 6 columns. Here is an example
bombardmentID, particleID, depth, x, y, z
3, 0, 0, 1.70705e+08, -6.06866e+07, 4.03509e+08
4, 0, 0, -4.90489e+08, -2.02786e+08, 2.654e+08
1, 0, 0, -1.17807e+08, 8.74504e+06, 2.74198e+08
- The bombardmentID is the simulation number. Each bombardment is independent from the other.
- The particleID is an identifier for each particle generated in a simulation. particleID 0 is the original particle, while all other particles have an ID of 1 or more.
- The depth is the cascade generation number of the particle. When a particle displaces a substrate atom, that substrate particle is given a particleID and a depth of 1 more than the parent particle.
- x,y,and z are the respective coordinates.
A python script is located in the /python directory called graphing.py. To use it, ensure you have python installed. In addition, you will need to install the pandas and matplotlib libraries.
Install these using
pip install pandas
pip install matplotlibAfter you've run AMCSET, you can generate a plot using this script like so (run this from the /build directory).
../python/graphing.pyBelow is a list of planned features that are not yet implemented in the program. There are three different types of planned features
- (Required) Sections marked as Required are features that should be an inherent part of the program -- they cannot be controlled by the user. They are inherent program behavior that should be the only behavior of the program, with no option to disable it.
- (Option) Sections marked as Option are features that can be toggled by the user. These are optional features that are not critical to the program's function.
- (Development) These are codebase features that should be implemented to make development go by more smoothly. They do not affect the final program's behavior, only the development process.
Currently this project is only tested to build and run on Linux. Windows support should be added.
While this file tracks planned features, they should also be added to the GitHub page as issues. Similarly, issues should also be added to GitHub.
The program should be able to interpret and respond to signals such as SIGINT (Usually sent my Ctrl+C) by stopping any file I/O and writing a file end marker to the output file.
In addition to the primary output file, an auxillary information file should be created which contains information about the simulation
A graphical interface should be created upon running the program. This should be the default behavior, unless the program is specifically invoked through the command line with a flag disabling it.
The user should be able to specify settings, such as the substrate isotope/element, as well as the ion isotope/element (if an ion). They should also be able to run the program and view the data, all inside the interface. Ideally this should be implemented using a modern UI interface. Some promising candidates are:
Currently, the code does not change the number of grouped substrate interactions for electrons with very small or very large energy. This can prove to be a problem for very high energy electrons, where total flying distance become exceedingly large, and for low energies, where the lack of granular elastic energy calculations could result in a negative electron energy. The number of flying distances should be reduced in both cases.
The program should have an option to enable/disable output file compression. It should be able to compress output to .7z or .zip files.
Other output filetypes should be supported. While .csv files are ubiquitous, they are not good for extremely large files (like those that can be generated by this program) as they are very simple files (text separated by commas, as indiacted by the file extension, .CommaSeparatedList, or .csv).
Currently the program does not check the bounds on the energy of particles before performing calculations. This is especially important for electron bombardment calculations, where several of the calculations made are only valid for certain ranges of energy. The program should check that the user-provided energy is within the energy bounds of the calculation.
The codebase should be tested using Google gtest to ensure that the program works between updates. This should be integrated with GitHub to ensure that code that does not function correctly is not accidentally merged into the main branch.
The code should be able to leverage the GPU to perform parallelized calculations on a large scale. The most promising candidate for this option is the function for generating Mott Differential Cross Sections. This function is a major bottleneck for electron bombardment simulation (determined by performance analysis). Parallelizing this operation using a GPU may result in drastic speedups.
Due to the non-standardized nature of GPU-Accelerated programming (NVidea uses CUDA, AMD uses ROCm, Intel uses OpenCL) multiple GPU-Acceleration algorithms may need to be implemented depending on the system configuration.
SYCL is a promising library which attempts to unify the many different GPU vendors under a single development library. Using this can avoid multiple implementations, but may be less performant.
The Mott scattering differential cross section calculation is a major bottleneck in the code. It involves exponentiation and many array accesses to calculate a single differential cross section for a particular energy.
However, this is a deterministic function, albeit a complicated one. The results for certain energies can be cached and used by multiple threads to reduce the computational workload for large simulations. Bins should be sufficiently small to ensure that accuracy is not lost. A promising data structure for this purpose is std::unordered_map.
Currently, the default settings (in constants.h) and default settings file image (in utilities.h). These should be unified so that a change in the default settings in constants.h is reflected in the settingsMessage variable.
The Mott Scattering Parameters and Electron Screening Parameters are currently read in from a separate file. While this functionality is useful, an option should also be provided to regenerate the files from the executable in case the files are lost. This is similar to the existing settings preservation settings, where if the "settings.txt" cannot be located, a new one is generated.
In order to get tests to run properly, the main function was wrapped in a function called AMCSET(). and a separate header file was made for it. However, the input stream (which is passed as an argument to the wrapper) is not properly passed through the InputFields class, and is instead passed as a parameter to several functions which read the standard output, either directly or indirectly. This behavior is undesirable as it makes function signatures unnecessarily complicated and should be corrected.
Add the input stream reference (std::istream& inputStream) as a member in the InputFields class so that it can be better handled.
Currently several user-interface functions (those in utilities.cpp) are not wrapped with objects, and are in the global scope. This is bad practice that can lead to disorganized code. The I/O functions should be wrapped into an IOHandler class which manages I/O operations through member variables and functions.
While the project has a license file, the project is not yet properly licensed. It needs a copyright disclaimer, as well as proper header files with the copyright notice. Notice should be aquired from Dr. Shao and any other invested parties before proper licensing is enforced.
It should adhere to the GNU Licensing Guidelines.
- The command line progress bar does not properly clear at the end of a run.
- Image at the top of the markdown file as axis multipliers of "10e8", but are only partially visible. The graph was generated using matplotlib.pylot.
I am a chemical engineer working on my PhD in nuclear engineering. I have a passion for molten salt corrosion research, with hopes of applying my computational knowledge and skills towards solving corrosion problems in molten salt reactors. This particular project is important to me, as it is relevant to predicting irradiation effects in nuclear materials, a particularly important problem in my field.
In my free time, I love to play piano, swim, play video games, and program.
- Name: Nathaniel Thomas
- Email: nathaniel@swbell.net
- GitHub: github.com/At11011
This projoect will be licensed under the GNU General Public License v2.0 - see the LICENSE file for details.
Currently the licensing is not yet properly implemented. See proper Proper Licensing (Development) for details.
All credit goes to Dr. Lin Shao at Texas A&M University for providing the original implementation of this software using QuickBASIC. His program included ion and electron bombardment support, as well as the novel flying-distance grouping method and the midpoint energy approximation method that drastically improved the performance of electron bombardment calculations while still maintaining high accuracy.
This program builds upon his original work by improving the ease of use (settings file instead of CLI input), as well as performance improvements.
Thanks to Kenneth Cooper and Benjamin Mejia Diaz for their help in reviewing this code.