Skip to content

Bindings: Python

Jump to bottom
Jon Drobny edited this page Jun 4, 2023 · 37 revisions

Installing Python bindings

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

First, the Python bindings require the following Python3 modules to be installed:

  • setuptools_rust
  • testresources
  • 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.

Sputtering Yields and Reflection Coefficients

As of v2.0.0, RustBCA includes a simple function for calculating sputtering yields or reflection coefficients of homogeneous, single-species materials. 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)

Python Bindings Example

examples/test_rustbca.py uses simple_bca_list_py() to simulate 1 keV helium on tungsten. To run, you need the Python bindings installed (see above), matplotlib, and numpy. It compares the sputtering yield to Yamamura's formula and the reflection coefficient to Thomas' formula. Differences between RustBCA simulation results and these formulas at moderate energy should be within 10% for most materials; it also produces the sputtered energy distribution and the implanted depth distribution using matplotlib, displayed below.

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:

Running RustBCA for 100000 He ions on W at 1.0 keV...
This may take several minutes.
Simulation complete. Processing data...
Data processing complete.
RustBCA Y: 0.0287 Yamamura Y: 0.025479590898842535
RustBCA R: 0.50558 Thomas R: 0.4780755087527244
Time per ion: 1.192930190563202 us/He

Helium on tungsten depth distribution, with a peak at 70 Angstroms

Implanted helium on tungsten at 1 keV

Helium on tungsten sputtered energy distributions

Energy distribution of tungsten sputtered by helium at 1 keV

Compound, list-based BCA in Python

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.
  • Ec (list(f64))`: ion cutoff energies in eV. If ion energy < Ec1, it stops in the material.
  • Es (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 lists 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

Parameters for Simple BCA

simple_bca_py and simple_bca_list_py can be used for simple targets (that is, targets made of one species instead of compound targets).

  • x, y, z: starting position in angstroms (Recommended: 0, 0, 0); Note: not used for simple_bca_list_py
  • ux, uy, uz: initial direction(s); Note: ux cannot be exactly 0 due to gimbal lock.
  • E: energy/energies in eV
  • Z1: atomic number(s) of incident ion(s)
  • M1: atomic mass(es) of incident ion(s) (amu)
  • Ec1: cutoff energy/energies of incident ion (eV)
  • Es1: surface binding energy/energies of incident ion (eV)
  • Z2: atomic number of material
  • M2: atomic mass of material (amu)
  • Ec2: cutoff energyof material (eV)
  • Es2: surface binding energyof material (eV)
  • n2: number density of material (1/angstrom^3)
  • Eb2: bulk binding energy of material (eV)

Output format

The output of simple_bca_list_py is a list of output particles with the following parameters:

[[Z, m (amu), E (eV) x (Angstrom), y (Angstrom), z (Angstrom), ux, uy, uz], ...]

Note that this includes implanted particles (with E < Es & x > 0), reflected particles (with E > 0 & x < 0), and sputtered particles (Z = Z_target & x < 0 & E > 0). See examples/test_rustbca.py for an example of filtering the output for implanted, reflected, and sputtered particles.

Clone this wiki locally