Bindings: Python

Installing Python bindings

Note: PyO3 May not build correctly on MacOS. See Issue #143

First, the Python bindings may require the following:

setuptools_rust, available on pip
testresources, available on pip
rustc must be available on your system PATH.
On Windows machines, you may need to install the Visual Studio C++ Build Tools.

Running the following command in the RustBCA directory: python3 -m pip install .

Will compile RustBCA as a library, construct the Python bindings, and build a python module, libRustBCA, that can be immediately imported into any Python script. An annotated example, test_rustbca.py, is included in the examples folder and elaborated upon in a following section.

Sputtering Yields and Reflection Coefficients

As of v2.0.0, RustBCA includes simple functions for calculating sputtering yields or reflection coefficients. R_N is the particle reflection coefficient (number of reflected particles divided by the number of incident particles) and R_E is the energy reflection coefficient (summed energy of reflected particles divided by summed energy of incident particles). These can be accessed in the following way:

from scripts.materials import *
from libRustBCA import *

energy = 1000.0 #eV
angle = 0.0 #degrees w.r.t. surface normal
num_samples = 1000

Y = sputtering_yield(hydrogen, tungsten, energy, angle, num_samples)
R_N, R_E = reflection_coefficient(hydrogen, tungsten, energy, angle, num_samples)
# Compounds are specified using number densities, e.g. 10% hydrogen to tungsten:
R_N, R_E = compound_reflection_coefficient(hydrogen, [tungsten, hydrogen], [tungsten['n'], 0.1*tungsten['n']], energy, angle, num_samples)

Note that these functions use the default options specified in the page on RustBCA's Input Files. Default options have been selected to provide the most accurate results for the widest range of anticipated use-cases, but in certain situations, such as very high or very low energy, the standalone code should be used instead so that these options can be modified directly.

Python Bindings Example: test_rustbca.py

examples/test_rustbca.py includes example usage of each Python function, including rotate_given_surface_normal_py, rotate_back_py, sputtering_yield, reflection_coefficient, compound_reflection coefficient, reflect_single_ion_py, simple_bca_list_py, compound_bca_list_1D_py, and as of writing on the dev branch, compound_bca_list_tracked_py, rotate_given_surface_normal_vec_py and rotate_back_vec_py.

To run the example, simply call the script from the command line:

C:\rustbca>python examples\test_rustbca.py
or
username@PCNAME:/rustbca$python3 examples/test_rustbca.py

Sample output of test_rustbca.py looks like this:

Before rotation: (1.0, 0.0, 0.0)
After rotation: (0.7071067811865476, -0.7071067811865477, 0.0)
After rotation back: (1.0, 0.0, 0.0)
Time to rotate: 5.689425468444825e-07 sec/vector
Sputtering yield for He on W at 2500.0 eV is 0.032 at/ion. Yamamura predicts 0.039 at/ion.
Particle reflection coefficient for He on W at 2500.0 eV is 0.438. Thomas predicts 0.414.
Energy reflection coefficient for He on W at 2500.0 eV is 0.24229632264696785
Particle reflection coefficient for He on HexW where x=0.1 at 2500.0 eV is 0.438. Thomas predicts 0.414.
Energy reflection coefficient for HexW where x=0.1 at 2500.0 eV is 0.25298977482459056
(vx, vy, vz) before reflection: (100000.0, 100000.0, 0.0)
(vx, vy, vz) after reflection: (0.0, 0.0, 0.0)
Running RustBCA for 10000 He ions on W at 1.0 keV...
This may take several minutes.
Simulation complete. Processing data...
Data processing complete.
RustBCA Y: 0.0324 Yamamura Y: 0.025479590898842535
RustBCA R: 0.5066 Thomas R: 0.4780755087527244
Time per ion: 0.00036274335384368895 s/He
Running RustBCA for 10000 He ions on W with hydrogenated layer at 1.0 keV...
This may take several minutes.
Running tracked RustBCA for 10000 He ions on W with 1% He at 1.0 keV...
This may take several minutes.
Data processing complete.
RustBCA Y: 0.0304 Yamamura Y: 0.025479590898842535
RustBCA R: 0.5195 Thomas R: 0.4780755087527244
Time per ion: 0.00015853838920593263 s/He

Python helper functions

libRustBCA contains several helper functions to make coupling RustBCA to plasma simulations simpler.

rotate_given_surface_normal_py(nx, ny, nz, ux, uy, uz)

This function is for rotating vectors in arbitrary global coordinates into local RustBCA coordinates (+x into the surface). A typical use case would involve a particle from a plasma simulation hitting a wall, its direction vector being rotated into RustBCA coordinates using the surface normal vector (nx, ny, nz), a RustBCA simulation being run, and then the emitted direction vector would be rotated back into the global simulation coordinates with rotate_back_py.

Args:

nx (f64): surface normal vector x component in global coordinates
ny (f64): surface normal vector y component in global coordinates
nz (f64): surface normal vector z component in global coordinates
ux (f64): input unit vector x component in global coordinates
uy (f64): input unit vector y component in global coordinates
uz (f64): input unit vector z component in global coordinates

Returns:

ux (f64): input unit vector x component in RustBCA coordinates
uy (f64): input unit vector y component in RustBCA coordinates
uz (f64): input unit vector z component in RustBCA coordinates

rotate_back_py(nx, ny, nz, ux, uy, uz)

This function is intended to complement rotate_given_surface_normal_py. It calculates the inverse rotation, transforming from local RustBCA coordinates to global coordinates specified by the surface normal vector (nx, ny, nz).

Args:

nx (f64): surface normal vector x component in global coordinates
ny (f64): surface normal vector y component in global coordinates
nz (f64): surface normal vector z component in global coordinates
ux (f64): input unit vector x component in RustBCA coordinates
uy (f64): input unit vector y component in RustBCA coordinates
uz (f64): input unit vector z component in RustBCA coordinates

Returns:

ux (f64): input unit vector x component in global coordinates
uy (f64): input unit vector y component in global coordinates
uz (f64): input unit vector z component in global coordinates

rotate_given_surface_normal_vec_py(nx, ny, nz, ux, uy, uz)

This function is the same as rotate_given_surface_normal_py but all inputs are now lists and the function is both vectorized and parallelized; it should appropriately collect the number of threads from the machine, but if it needs to be specified it can be by setting the environment variable RAYON_NUM_THREADS. See more information in the rayon, the parallelization crate RustBCA uses, FAQ here.

Args:

nx (list(f64)): list of surface normal vector x components in global coordinates
ny (list(f64)): list of surface normal vector y components in global coordinates
nz (list(f64)): list of surface normal vector z components in global coordinates
ux (list(f64)): list of input unit vector x components in global coordinates
uy (list(f64)): list of input unit vector y components in global coordinates
uz (list(f64)): list of input unit vector z components in global coordinates

Returns:

ux (list(f64)): list of input unit vector x components in RustBCA coordinates
uy (list(f64)): list of input unit vector y components in RustBCA coordinates
uz (list(f64)): list of input unit vector z components in RustBCA coordinates

rotate_back_vec_py

This function is the same as rotate_given_surface_normal_py but all inputs are now lists and the function is both vectorized and parallelized; it should appropriately collect the number of threads from the machine, but if it needs to be specified it can be by setting the environment variable RAYON_NUM_THREADS. See more information in the rayon, the parallelization crate RustBCA uses, FAQ here.

Args:

nx (list(f64)): list of surface normal vector x components in global coordinates
ny (list(f64)): list of surface normal vector y components in global coordinates
nz (list(f64)): list of surface normal vector z components in global coordinates
ux (list(f64)): list of input unit vector x components in RustBCA coordinates
uy (list(f64)): list of input unit vector y components in RustBCA coordinates
uz (list(f64)): list of input unit vector z components in RustBCA coordinates

Returns:

ux (list(f64)): list of input unit vector x components in global coordinates
uy (list(f64)): list of input unit vector y components in global coordinates
uz (list(f64)): list of input unit vector z components in global coordinates

Python single-ion BCA functions

This function is intended for use in code-coupling for modeling the reflection, neglecting sputtering, of energetic ions from a homogeneous, mono-elemental target.

reflect_single_ion_py

Python full BCA functions

These functions allow for a full BCA simulation in Python with various features en/disabled. All of these share a similar interface - generally, they output an Nx9 list of lists that contains all incident (stopped and reflected) and sputtered particles resulting from the specified simulation. Some also output various boolean or integer arrays that store information about each computational particle returned.

The output arrays share a common column order: [Z, m, E, x, y, z, ux, uy, uz], where Z is the atomic number of the output particle, m the atomic mass in amu, E the energy in eV, (x, y, z) the final position of the particle (relative to a starting position just above (0, 0, 0)), and (ux, uy, uz) the normal vector representing the final direction of the particle.

To filter the output array, one can distinguish the particles in the following way:

If a particle is incident (by checking an incident output list or comparing atomic numbers), it can be either reflected or stopped. If E > 0 **and **x < 0, the particle was reflected. Otherwise, it was stopped in the target. If the particle was not incident, it was sputtered.