RustBCA
RustBCA
is a general-purpose, high-performance code for simulating
ion-material interactions including sputtering, reflection, and implantation
using the binary collision approximation (BCA), written in Rust!
RustBCA includes a standalone version and libraries for including
ion-material interactions in simulations written in C/C++, Python,
and Fortran.
By discretizing the collision cascade into a sequence of binary collisions, BCA codes can accurately and efficiently model the prompt interaction between an energetic ion and a target material. This includes reflection, implantation, and transmission of the incident ion, as well as sputtering and displacement damage of the target. Generally, BCA codes can be valid for incident ion energies between approximately ~1 eV/nucleon to <1 GeV/nucleon. Improvements to RustBCA have expanded the regime of validity for some quantities, such as reflection coefficients, below 1 eV/nucleon.
Check out the RustBCA
Wiki for detailed information, installation
instructions, use cases, examples, and more. See the RustBCA paper at the
Journal of Open Source Software by clicking the badge below:
Selected citations of RustBCA as of 5/24/23:
The easiest way to get started is with the ergonomic Python functions. Follow these steps to install, build, and run simple RustBCA simulations for sputtering yields and reflection coefficients:
git clone https://github.com/lcpp-org/rustbca
cd rustbca
python -m pip install .
python
Python 3.9.6 (tags/v3.9.6:db3ff76, Jun 28 2021, 15:26:21) [MSC v.1929 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> from libRustBCA import *; from scripts.materials import *
>>> angle = 0.0 # deg
>>> energy = 1000.0 # eV
>>> num_samples = 10000
>>> sputtering_yield(argon, tungsten, energy, angle, num_samples)
1.0398
>>> reflection_coefficient(argon, tungsten, energy, angle, num_samples)
(0.3294, 0.10230906775743769) # (reflection coefficient, energy reflection coefficient)
>>>
For those eager to get started with the standalone code, try running one of the examples in the
RustBCA/examples
directory. Note that to automatically manipulate input files and reproduce
the plots located on the Wiki, these may require some optional
Python packages (matplotlib
, numpy
, scipy
, shapely
, and toml
).
First, run the example using:
cargo run --release examples/boron_nitride.toml
Afterwords, fire up your favourite Python interpreter (e.g., IPython) and execute:
from scripts.rustbca import *
do_trajectory_plot("boron_dust_grain_")
First, run the example using:
cargo run --release examples/layered_geometry.toml
Afterwords, fire up your favourite Python interpreter (e.g., IPython) and execute:
import numpy as np
import matplotlib.pyplot as plt
deposited_ions = np.genfromtxt(
"2000.0eV_0.0001deg_He_TiO2_Al_Sideposited.output",
delimiter=",",
names=["M", "Z", "x", "y", "z", "collisions"],
)
plt.hist(deposited_ions["x"], bins=100)
plt.show()
The following features are implemented in RustBCA
:
csv
format) and include:
--features distributions
flag and disable space-intensive particle list output with --features no_list_output
.Without optional features, RustBCA
should compile with cargo
alone on
Windows, MacOS, and Linux systems.
HDF5 for particle list input has been tested on Windows, but version 1.10.6 must be used.
cargo
, the Rust package manager, rustc
, the Rust compiler, and more).curl
:
sudo apt-get install curl
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
pip
for Python:
sudo apt-get install python3-pip
python3 -m pip install numpy matplotlib shapely scipy
git clone https://github.com/uiri/toml.git
cd toml
python3 setup.py install
sudo apt-get install gcc gfortran build-essential cmake liblapack-dev libblas-dev liblapacke-dev
cargo
:
sudo apt-get install cargo
RustBCA
:
git clone https://github.com/lcpp-org/rustBCA
cd RustBCA
cargo build --release
RustBCA
with optional dependencies, hdf5
and/or rcpr
(with your choice of backend: openblas
, netlib
, or intel-mkl
):
cargo build --release --features cpr_rootfinder_netlib,hdf5_input
cargo build --release --features cpr_rootfinder_openblas,hdf5_input
cargo build --release --features cpr_rootfinder_intel_mkl,hdf5_input
input.toml
is the input file - see Usage for more informationcargo test
cargo test --features cpr_rootfinder_netlib
cargo test --features cpr_rootfinder_openblas
cargo test --features cpr_rootfinder_intel_mkl
Most of the ingredients for building RustBCA
and running the Python helper
scripts are available natively in the Fedora software repository, so the setup
is relatively painless.
The Rust toolchain can be aquired using:
sudo dnf install rust rust-src rust-std-static rust-analysis rust-gdb rust-lldb rustfmt
The (optional) Python packages can be obtained using:
sudo dnf install python3-numpy python3-scipy python3-matplotlib python3-toml python3-shapely
or, alternatively, using pip3
.
If desired, RustBCA can be built with rcpr to simulate attractive-repuslive interaction potentials; rcpr requires (at least) the following:
sudo dnf install gcc gcc-gfortran cmake lapack lapack-devel blas blas-devel
Building RustBCA
is straightforward, and can be done using:
git clone https://github.com/lcpp-org/rustBCA
cd RustBCA
cargo build --release
with all of the explicit dependencies listed in Cargo.toml
handled
automatically during the build.
To use RustBCA
, modify an input.toml
file, which is used to configure each
simulation.
To run a simulation, execute:
./RustBCA
with input.toml
in the same directory as RustBCA
.
Alternatively, RustBCA
accepts the name of a.toml
input file as a single
command line argument.
./RustBCA /path/to/input.toml
Additionally, RustBCA
accepts an input file type (one of: 0D
, 1D
, 2D
, TRIMESH
, SPHERE
- see the wiki for more details):
./RustBCA 0D /path/to/input.toml
Warning: RustBCA defaults to the 2D triangular mesh input mode. For more details, see Input Files. Also have a look at the examples on the Wiki to see some examples of RustBCA input files.