Skip to content

Bindings: Python

Jump to bottom
Jon Drobny edited this page Apr 16, 2025 · 55 revisions

RustBCA includes a Python module, libRustBCA, that provides interfaces and helper functions to RustBCA in Python. These functions allow the user to run RustBCA from Python and couple plasma simulation codes directly to RustBCA via Python.

Note: unless otherwise noted, libRustBCA uses the default input options described in the Input Files page; users should review the default options to ensure they are appropriate for their use-case before proceeding.

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 libRustBCA, which can be immediately imported into any Python terminal or 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

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).

sputtering_yield(ion, target, energy, angle, num_samples)

Args:

  • ion (dict): A dictionary representing the ion properties; see scripts/materials.py for examples.
  • target (dict): A dictionary representing the target properties; see scripts/materials.py for examples.
  • energy (f64): incident energy of the ions in eV
  • angle (f64): incident angle measured from surface normal in degrees
  • num_samples (int): number of computational ions to simulate; typical computational time is 1 microsecond/ion/eV.

Returns:

  • Y (f64): sputtering yield in atoms/ion.

reflection_coefficient(ion, target, energy, angle, num_samples)

Args:

  • ion (dict): A dictionary representing the ion properties; see scripts/materials.py for examples.
  • target (dict): A dictionary representing the target properties; see scripts/materials.py for examples.
  • energy (f64): incident energy of the ions in eV
  • angle (f64): incident angle measured from surface normal in degrees
  • num_samples (int): number of computational ions to simulate; typical computational time is 1 microsecond/ion/eV.

Returns:

  • R_N (f64): particle reflection coefficient
  • R_E (f64): energy reflection coefficient. Note: because R_E is total emitted energy divided by incident energy, average emitted energy is E0*R_E/R_N.

compound_reflection_coefficient(ion, target_species, target_densities, angle, num_samples)

Args:

  • ion (dict): A dictionary representing the ion properties; see scripts/materials.py for examples.
  • target_species (list(dict)): A list of dictionaries representing the properties of the target species; see scripts/materials.py for examples.
  • target_densities (list(f64)): A list of the number densities of each species specified in target_species in the target in inverse cubic angstroms.
  • energy (f64): incident energy of the ions in eV
  • angle (f64): incident angle measured from surface normal in degrees
  • num_samples (int): number of computational ions to simulate; typical computational time is 1 microsecond/ion/eV.

Returns:

  • R_N (f64): particle reflection coefficient
  • R_E (f64): energy reflection coefficient. Note: because R_E is total emitted energy divided by incident energy, _average _emitted energy is E0*R_E/R_N.

These can be used 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 and the default material properties defined in scripts/materials.py. 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. It is recommended that the values of the parameters in scripts/materials.py be checked before usage.

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 unit vectors from 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.

The algorithm for constructing the relevant rotation matrices is documented here.

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; will be normalized to magnitude 1
  • uy (f64): input unit vector y component in global coordinates; will be normalized to magnitude 1
  • uz (f64): input unit vector z component in global coordinates; will be normalized to magnitude 1

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 will be normalized to magnitude 1
  • uy (list(f64)): list of input unit vector y components in RustBCA coordinates will be normalized to magnitude 1
  • uz (list(f64)): list of input unit vector z components in RustBCA coordinates will be normalized to magnitude 1

rotate_back_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 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 full BCA functions

These functions allow for a full BCA simulation in Python with various features enabled. All of these share a similar interface - generally, they output an Nx9 (where N is the number of incident particles plus the number of sputtered atoms) list of lists that contains all incident (stopped and reflected) and sputtered particles resulting from the specified simulation. Some functions also output various boolean or integer arrays that store information about each computational particle returned, such as whether the particle in question was originally incident, or the index of the incident particle that spawned the emitted particle.

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.

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

simple_bca_list_py(energies, ux, uy, uz, Z1, m1, Ec1, Es1, Z2, m2, Ec2, Es2, n2, Eb2)

This function runs a 0D Binary Collision Approximation simulation for the given incident ions and material.

Args:

  • energy (list(f64)): initial energies in eV.
  • ux (list(f64)): initial ion directions x. Note: ux != 0.0 to avoid gimbal lock
  • uy (list(f64)): initial ion directions y.
  • uz (list(f64)): initial ion directions z.
  • Z1 (f64): initial ion atomic number.
  • m1 (f64): initial ion mass in amu.
  • Ec1 (f64): ion cutoff energy in eV. If ion energy < Ec1, it stops in the material.
  • Es1 (f64): ion surface binding energy. Assumed planar.
  • Z2 (f64): target material atomic number.
  • m2 (f64): target material mass in amu.
  • Ec2 (f64): target material cutoff energy in eV. If recoil energy < Ec2, it stops in the material.
  • Es2 (f64): target atom surface binding energy. Assumed planar.
  • n2 (f64): target material atomic number density in inverse cubic Angstroms.
  • Eb2 (f64): target material bulk binding energy in eV.

Returns:

  • output (NX9 list of f64): each row in the list represents an output particle (implanted, sputtered, or reflected). Each row consists of: [Z, m (amu), E (eV), x, y, z, (angstrom), ux, uy, uz]

compound_bca_list_py(ux, uy, uz, energy, Z1, m1, Ec1, Es1, Z2, m2, Ec2, Es2, n2, Eb2)

runs a BCA simulation for a list of particles and outputs a list of sputtered, reflected, and implanted particles.

Args:

  • energies (list(f64)): initial ion energies in eV.
  • ux (list(f64)): initial ion directions x. ux != 0.0 to avoid gimbal lock
  • uy (list(f64)): initial ion directions y.
  • uz (list(f64)): initial ion directions z.
  • Z1 (list(f64)): initial ion atomic numbers.
  • m1 (list(f64)): initial ion masses in amu.
  • Ec1 (list(f64)): ion cutoff energies in eV. If ion energy < Ec1, it stops in the material.
  • Es1 (list(f64)): ion surface binding energies. Assumed planar.
  • Z2 (list(f64)): target material species atomic numbers.
  • m2 (list(f64)): target material species masses in amu.
  • Ec2 (list(f64)): target material species cutoff energies in eV. If recoil energy < Ec2, it stops in the material.
  • Es2 (list(f64)): target species surface binding energies. Assumed planar.
  • n2 (list(f64)): target material species atomic number densities in inverse cubic Angstroms.
  • Eb2 (list(f64)): target material species bulk binding energies in eV.

Returns:

  • output (NX9 list of f64): each row in the list represents an output particle (implanted, sputtered, or reflected). Each row consists of: [Z, m (amu), E (eV), x, y, z, (angstrom), ux, uy, uz]
  • incident (list(bool)): whether each row of output was an incident ion or originated in the target

compound_bca_list_1D_py(ux, uy, uz, energies, Z1, m1, Ec1, Es1, Z2, m2, Ec2, Es2, Eb2 n2, dx)

runs a BCA simulation for a list of particles and outputs a list of sputtered, reflected, and implanted particles.

Args:

  • ux (list(f64)): initial ion directions x. ux != 0.0 to avoid gimbal lock
  • uy (list(f64)): initial ion directions y.
  • uz (list(f64)): initial ion directions z.
  • energies (list(f64)): initial ion energies in eV.
  • `Z1 (list(f64)): initial ion atomic numbers.
  • m1 (list(f64)): initial ion masses in amu.
  • Ec1 (list(f64)): ion cutoff energies in eV. If ion energy < Ec1, it stops in the material.
  • Es1 (list(f64)): ion surface binding energies. Assumed planar.
  • Z2 (list(f64)): target material species atomic numbers.
  • m2 (list(f64)): target material species masses in amu.
  • Ec2 (list(f64)): target material species cutoff energies in eV. If recoil energy < Ec2, it stops in the material.
  • Es2 (list(f64)): target species surface binding energies. Assumed planar.
  • Eb2 (list(f64)): target material species bulk binding energies in eV.
  • n2 (list(list(f64))): target material species atomic number densities in inverse cubic Angstroms.
  • dx (list(f64)): target material layer thicknesses starting at surface in Angstroms.

Returns:

  • output (NX9 list of f64): each row in the list represents an output particle (implanted, sputtered, or reflected). Each row consists of: [Z, m (amu), E (eV), x, y, z, (angstrom), ux, uy, uz]
  • incident (list(bool)): whether each row of output was an incident ion or originated in the target
  • stopped (list(bool)): whether each row of output is associated with a particle that stopped in the target

compound_bca_list_tracked_py(ux, uy, uz, energy, Z1, m1, Ec1, Es1, Z2, m2, Ec2, Es2, n2, Eb2)

This function runs a BCA simulation for a 1D, multi-elemental target for multiple ions. It tracks which incident particle sputtered which emitted particle by outputting an incident_index list. This can be used especially to keep track of where in a global simulation particles should be emitted based on where the incident particle that generated them impacted a wall.

Args:

  • energies (list(f64)): initial ion energies in eV.
  • ux (list(f64)): initial ion directions x. ux != 0.0 to avoid gimbal lock
  • uy (list(f64)): initial ion directions y.
  • uz (list(f64)): initial ion directions z.
  • Z1 (list(f64)): initial ion atomic numbers.
  • m1 (list(f64)): initial ion masses in amu.
  • Ec1 (list(f64)): ion cutoff energies in eV. If ion energy < Ec1, it stops in the material.
  • Es1 (list(f64)): ion surface binding energies. Assumed planar.
  • Z2 (list(f64)): target material species atomic numbers.
  • m2 (list(f64)): target material species masses in amu.
  • Ec2 (list(f64)): target material species cutoff energies in eV. If recoil energy < Ec2, it stops in the material.
  • Es2 (list(f64)): target species surface binding energies. Assumed planar.
  • n2 (list(f64)): target material species atomic number densities in inverse cubic Angstroms.
  • Eb2 (list(f64)): target material species bulk binding energies in eV.

Returns:

  • output (NX9 list of f64): each row in the list represents an output particle (implanted,sputtered, or reflected). Each row consists of: [Z, m (amu), E (eV), x, y, z, (angstrom), ux, uy, uz]
  • incident (list(bool)): whether each row of output was an incident ion or originated in the target
  • incident_index (list(usize)): index of incident particle that caused this particle to be emitted

Python single ion functions

reflect_single_ion_py(ion, target, vx, vy, vz)

This function is intended for use in code-coupling for modeling the reflection, neglecting sputtering, of energetic ions from a homogeneous, mono-elemental target. NOTE: unlike other RustBCA functions, it uses velocity coordinates instead of energy-direction coordinates.

Args:

  • ion (dict): a dictionary defining the incident ions that includes keys 'Z', the atomic number, 'm', the atomic mass in amu, 'Ec', the cutoff energy in eV, and 'Es', the surface binding energy in eV.
  • target (dict): a dictionary defining the target material that includes keys 'Z', the atomic number, 'm', the atomic mass in amu, 'Ec', the cutoff energy in eV, 'Es', the surface binding energy in eV, 'Eb', the bulk binding energy in eV, and 'n', the number density in 1/m3.
  • vx (f64): the x-velocity in m/s (+x into the surface).
  • vy (f64): the y-velocity in m/s
  • vz (f64): the z-velocity in m/s

simple_bca_py(x, y, z, ux, uy, uz, energy, Z1, m1, Ec1, Es1, Z2, m2, Ec2, Es2, n2, Eb2)

This function runs a BCA simulation for a given incident ion and homogeneous, monoelemental target material. It shares a common interface with the full BCA simulation functions above.

Args:

  • x (f64): initial ion position x in m. Material is x>0. Best results are obtained starting the ion 1 ion mfp above the surface, where mfp = 1/n^3.
  • y (f64): initial ion position y in m. Material is infinite in y
  • z (f64): initial ion position z in m. Material is infinite in z
  • ux (f64): intial ion direction in x. +x is into the surface.
  • uy (f64): initial ion direction in y.
  • uz (f64): initial ion direction in z.
  • energy (f64): initial ion energy in eV.
  • Z1 (f64): atomic number of incident ion.
  • m1 (f64): atomic mass of incident ion in amu.
  • Ec1 (f64): cutoff energy of incident ion in eV.
  • Es1 (f64): surface binding energy of incident ion in eV.
  • Z2 (f64): target atomic number.
  • m2 (f64): target atomic mass in amu.
  • Ec2 (f64): target cutoff energy in eV.
  • Es2 (f64): target surface binding energy in eV.
  • n2 (f64): target atomic number density in 1/m3.
  • Eb2 (f64): target bulk binding energy in eV.

Returns:

  • output (Nx9 list of f64): each row in the list represents an output particle (implanted, sputtered, or reflected). N will be greater than or equal to 1. Each row consists of: [Z, m (amu), E (eV), x, y, z, (angstrom), ux, uy, uz].

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

Click Pages above to see all pages in the Wiki.

Start Here

Home page

Installation

Selected Benchmarks

Frequently Asked Questions

FAQ

This page is a work in progress.

Using the Standalone Code

Input Files

Output Files

Error Messages

Interaction Potentials

Standalone Code Examples

Layered Targets

2D Geometry

Spherical Geometry

3D Geometry

Gaseous Targets

Multiple Interaction Potentials

Output Histograms

Bindings

Python

C/C++

Fortran

Clone this wiki locally