Beam distributions¶
A beam is rarely one energy and one angle. Real implanters give an energy spread, a divergence, a spot size. pysrim2 lets each beam parameter be a distribution: the ion energy, the angle of incidence, the azimuth around the beam axis, and the start position. A run with distributions samples the beam and then runs SRIM on it.
A run spec without distributions is unchanged, so all earlier scripts and run.yaml
files keep working (see run.yaml).
Two modes¶
Set the mode with beam: {mode: ...} in the run spec. exact is the default.
|
|
|
|---|---|---|
What SRIM runs |
every sampled ion, from a |
one run per bin of the energy and angle |
Faithful to the sampled beam |
yes, each ion has its own energy and direction |
approximate: a bin’s ions share the bin’s mean energy and angle |
Parameters |
energy, angle, azimuth, position |
energy, angle, and azimuth only if uniform over the full turn |
SRIM calculation |
4 (for |
the spec’s own |
Ions per SRIM run |
at most 99 999 |
no limit: the ions are split over the bins |
Parallel |
a run of up to 99 999 ions is one SRIM process; bigger beams are split into units |
every bin is a unit, run on the scan workers |
Cache |
in a scan, every unit (a bin, or a unit of 99 999 ions) is cached |
in a scan, every bin is cached, so a repeated scan reruns nothing |
Use exact when the start position or the azimuth matters, when you want the
sampled ions themselves (for example to check the sampling), or when you have up to a
few hundred thousand ions. Use binned for large ion counts when only energy and
tilt are spread: each bin is one SRIM run, and the bins run in parallel.
Binned mode is an approximation. Within a bin every ion has the bin’s mean energy and angle, so more bins give a closer answer and more SRIM runs. Exact mode has no such error: SRIM runs every sampled ion with its own energy, direction and start position.
Quick start¶
A distributed run in Python. Build the run spec with TRIM(...), then replace the
energy with a distribution. Gaussian(20.0, 1.0) is 20 keV with a standard deviation
of 1 keV.
from srim import TRIM, Ion, Layer, Target
from srim.analysis import implant_summary
from srim.beam import Gaussian, run_beam, sampled_ions
from srim.spec import RunSpec
target = Target([Layer.from_formula("Si", density=2.33, width=10000.0)]) # 1000 nm
data = (
TRIM(target, Ion("B", energy=20e3), number_ions=200, calculation=1, ranges=1, random_seed=12345)
.to_spec()
.to_dict()
)
data["ion"]["energy_keV"] = Gaussian(20.0, 1.0).to_dict()
spec = RunSpec.from_dict(data)
if __name__ == "__main__": # required for binned beams (worker processes import this file)
with run_beam(spec, output_dir="beam-exact") as results:
print(implant_summary(results.range3d.df)["mean_depth_A"])
print(sampled_ions(results)[["ion", "energy_keV", "depth_nm"]].head())
The same beam in YAML. beam: is optional here: exact is the default.
version: 1
spec:
ion:
symbol: B
energy_keV: {gaussian: {mean: 20.0, sigma: 1.0}}
angle_deg: 0.0
number_ions: 200
calculation: 1
seed: 12345
settings: {description: pysrim run, ranges: 1}
target:
- name: Si
thickness_nm: 1000.0
density_g_cm3: 2.33
phase: 0
elements:
- {symbol: Si, stoich: 1.0, displacement_eV: 25.0, lattice_eV: 0.0, surface_eV: 3.0}
pysrim2 run beam.yaml --set beam.mode=binned --set beam.bins.energy_keV=5
pysrim2 run accepts a distributed run file and prints where its results are. The
--set keys are the same as for scans (see below).
Shapes¶
Every distribution is a one-key mapping in YAML, such as {gaussian: {mean: 20.0, sigma: 1.0}}. In Python, the classes in srim.beam give the same mapping with
.to_dict(). A number is a fixed value.
Shape |
YAML |
Python |
Density |
|---|---|---|---|
fixed |
|
|
one value (no spread) |
Gaussian |
|
|
normal |
uniform |
|
|
flat between |
triangular |
|
|
peak at |
log-normal |
|
|
|
histogram |
see histogram files |
|
piecewise constant |
Python function |
see Python functions |
|
your density |
Any shape can take range: [low, high] to cut its tails (truncation). Without it,
a Gaussian or a log-normal runs from mean ± 5 sigma (for a log-normal, exp(mu ± 5 sigma)).
The density is renormalised after the cut.
A zero-width shape (sigma: 0, or a uniform with low == high) is a fixed value.
beam.bins for a fixed parameter is an error, because there is nothing to bin.
Each continuous shape is tabulated on 4097 points of its support, and the sampled distribution is the piecewise-linear cumulative distribution through those points. Histograms are exact (their bin edges are the nodes).
Python:
from srim.beam import Fixed, Gaussian, LogNormal, Triangular, Uniform
energy = Gaussian(20.0, 1.0, range=(17.0, 23.0)) # truncated at 17 and 23 keV
angle = Uniform(0.0, 5.0).to_dict() # the mapping, for a run spec dict
YAML, with a truncation:
ion:
energy_keV: {gaussian: {mean: 20.0, sigma: 1.0, range: [17.0, 23.0]}}
angle_deg: {uniform: {low: 0.0, high: 5.0}}
Which parameters can be distributions¶
Key |
Exact |
Binned |
Notes |
|---|---|---|---|
|
yes |
yes |
cut to energies above 0 |
|
yes |
yes |
cut to |
|
yes |
uniform over |
cut to |
|
yes |
no |
|
ion.azimuth_deg is the direction around the beam axis. In exact mode a distributed
beam with no azimuth gets a uniform azimuth over the full turn, so the tilt is the
same for every ion but the ions spread around the axis. Give azimuth_deg: 0.0 to
put every ion in one plane. In binned mode the azimuth is not binned, so a uniform
azimuth over the full turn is accepted and a narrower one is refused (it needs exact
mode).
ion.position gives the start point in the target’s frame. y_nm and z_nm are the
lateral coordinates (default 0), and depth_nm is the depth (default 0). Position
distributions are exact-only:
ion:
energy_keV: 20.0
position:
y_nm: {gaussian: {mean: 0.0, sigma: 50.0}}
z_nm: {gaussian: {mean: 0.0, sigma: 50.0}}
depth_nm: 0.0
Each beam parameter is drawn on its own, so the energy, the angle and the position are independent. Correlated distributions (for example an energy that depends on the angle) are not possible. A beam has one ion species.
Truncation and physical limits¶
pysrim2 refuses a beam that differs from the one you defined, rather than running a
clipped one silently. Errors name the dotted key, for example
ion.energy_keV: no probability in [...]. These checks apply:
energy: only the part above 0 is sampled (
ion.energy_keV, must have probability above 0)angle: only
[0, 90)is sampledazimuth: only
[0, 360)is sampleddepth: the start depth must be inside the target,
[0, total thickness)
A range that leaves no probability is an error, and so is a range with low > high.
Histograms¶
A histogram is a piecewise-constant density. The counts are weights: they need not sum
to one. A histogram takes exactly one of three forms: a file; edges with counts; or
centres with counts. Examples, one per form:
ion:
energy_keV: {histogram: {file: energy_spectrum.txt}} # from a text file
ion:
angle_deg: {histogram: {edges: [0.0, 2.0, 4.0], counts: [1.0, 3.0]}} # edges and counts
ion:
angle_deg: {histogram: {centres: [1.0, 3.0], counts: [1.0, 3.0]}} # centres and counts
Python:
from srim.beam import Histogram
spectrum = Histogram.from_file("energy_spectrum.txt")
binned_by_centre = Histogram.from_centres([10, 20, 40], [1, 3, 1])
explicit = Histogram([0.0, 2.0, 4.0], [1.0, 3.0])
A relative file in a YAML file is taken from the folder of the YAML file. In Python it
is taken from the working directory. The spec stores the absolute path, and the cache
key and point id use the file’s content, so editing the file gives a new point.
Histogram files¶
A text file has one bin per line, in one of two layouts:
two columns,
centre count: the bin edges are the midpoints between centres, and the outer edges are half a bin beyond the first and last centre. Centres must increase.three columns,
low high count: one bin per line, in order. A gap between two bins becomes a bin with count 0. Bins must not overlap.
Rules that apply to both:
columns are separated by whitespace, tabs,
;or,when the separator is
;or a tab, a comma is a decimal mark (1,5;10is 1.5 and 10); when the separator is,, commas separate fields#starts a comment, blank lines are skipped, and CRLF line ends are accepteda first row with no digits is a header and is skipped
trailing empty fields (a final separator) are ignored
counts must not be negative and must have a positive sum
This file gives centres 10, 20 and 40 keV with counts 1, 3 and 1:
# energy spectrum, keV counts
energy_keV;counts
10,0;1
20,0;3
40,0;1
An error names the file and the line, for example
energy_spectrum.txt: line 3: centres must be strictly increasing.
Python functions¶
For a density that is not one of the shapes, give a module-level function. It must
accept a numpy array and return an array of the same shape (or a scalar, which is then
broadcast), with values that are finite and not negative. range is required and is the
support of the distribution. The density is tabulated on the same grid as the other
shapes.
A function is referred to as python:<module>:<name>. The module must be importable by
its name from the worker processes: put it next to your script (or on PYTHONPATH) and
run from that folder. Functions in __main__, lambdas and functions made inside another
function are refused, because a worker cannot import them.
my_beams.py:
import numpy as np
def ramp(energy_keV):
"""A density that rises linearly from 5 to 40 keV (vectorised)."""
return np.asarray(energy_keV, dtype=float)
Use it in YAML:
ion:
energy_keV: {function: {ref: "python:my_beams:ramp", range: [5.0, 40.0]}}
or in Python, where the function object is accepted too (it must be importable):
from srim.beam import Function
from my_beams import ramp
energy = Function("python:my_beams:ramp", range=(5.0, 40.0))
same = Function(ramp, range=(5.0, 40.0)) # stored as the same python: reference
The source text of the function is part of the cache key. Changing the function (or the module it is in) gives a new point, so an old run is never reused for a changed density.
Seeds and reproducibility¶
A spec’s seed decides the beam. Each sampled parameter has its own random stream,
spawned from the seed in a fixed order: energy, angle, azimuth, y, z, depth. The same
spec and seed give the same sampled beam and the same results on the same platform.
Because the streams are separate, adding a position to a spec does not change the
sampled energies.
Exact mode samples number_ions ions. A scan with several points gives each point a seed
derived from the scan’s seed and the point id (see Scans), so a point keeps its
seed when other points are added.
Running a beam¶
run_beam(spec) runs a distributed spec and returns its results. It chooses the route:
an exact beam of up to 99 999 ions is one SRIM run, the same as
TRIM.from_spec(spec).run();anything else is a one-point scan: a binned beam runs one SRIM run per bin, an exact beam of more ions is split into units of 99 999 ions, and
precision=(see precision targets in Scans) runs batches until a precision goal is met.
from srim.beam import run_beam
with run_beam(spec) as results: # a temporary folder, deleted by close()
...
with run_beam(spec, output_dir="beam-run") as results: # keeps the outputs
...
output_dir is the folder of a single run, or the scan folder of a scan (its point folder
is beam-run/points/<id[:16]>). Use results as a context manager, or call close(), to
delete the temporary folder.
What you get back¶
Exact single run: a srim.output.Results (with TRIM.DAT and run.yaml in its
directory, next to the usual outputs). Its per-ion tables (range3d, …) are the ions
SRIM ran.
Batched runs (an exact beam above 99 999 ions, a binned beam, or a precision target): a
srim.scan.MergedResults, with the surface of Results:
per-ion tables are concatenated.
ionis the global ion number, and abatchcolumn gives the unit (batch) each ion came from.a binned beam adds
beam_batch,bin,bin_energy_keVandbin_angle_degafterbatch.results.beam_binsis the table of the bins of a binned run (one row per bin, with the columns listed in DataFrames). It is None for an exact merged result. A single run’sResultshas no such attribute.
A finished point folder can be opened again, for example later or in another script. Pass
the point’s folder (points/<id[:16]>, under the output_dir of the run):
from pathlib import Path
from srim.beam import open_results
point = next(Path("beam-run/points").iterdir()) # the point folder of a finished binned run
with open_results(point) as results:
print(results.beam_bins)
The sampled ions¶
sampled_ions(results) reads the ions an exact run ran back from its TRIM.DAT file(s):
one row per ion, with the energy, the depth, the lateral position and the direction
cosines. For a merged result the units are concatenated, and batch gives the unit.
Binned results raise an error, because a binned run has no sampled ions (it has bins).
with run_beam(spec, output_dir="beam-exact") as results:
ions = sampled_ions(results)
print(ions[["ion", "energy_keV", "angle_deg", "azimuth_deg", "depth_nm"]].head())
The values come from the file, which stores 7 significant digits, so they can differ from the sampled values in the last digit.
Binned mode¶
In a binned run each distributed energy and angle is cut into bins, and every bin is one SRIM run with a fixed energy and angle.
beam.bins.energy_keVandbeam.bins.angle_deggive the number of bins. An integer gives equal-probability bins; a list gives the bin edges. The defaults are 10 energy bins and 6 angle bins.A bin’s energy and angle are the mean of the bin’s interval. With edges, probability outside the edges is dropped and the rest renormalised (a warning above 0.1 %).
The beam has one run per bin of the product (energy-major). Bins with no probability are dropped.
The ions are split over the bins by Webster (Sainte-Laguë) apportionment, so each bin gets its share of
number_ionsand the total is exact. A bin that gets no ion has no run.beam.max_bins(default 2000) caps the number of bins. More bins is an error that namesbeam.max_bins. More than 200 bins warns, because each bin is a SRIM run.The calculation is the one in the spec (1 or 2, or any other), not 4 or 5.
ion:
energy_keV: {gaussian: {mean: 20.0, sigma: 1.0}}
angle_deg: {uniform: {low: 0.0, high: 5.0}}
beam:
mode: binned
bins:
energy_keV: 8
angle_deg: [0.0, 2.5, 5.0]
max_bins: 500
Python (start from the spec of the quick start; run it inside the __main__ guard, as there):
from srim.beam import Uniform
data["ion"]["energy_keV"] = Gaussian(20.0, 1.0).to_dict()
data["ion"]["angle_deg"] = Uniform(0.0, 5.0).to_dict()
data["beam"] = {"mode": "binned", "bins": {"energy_keV": 8, "angle_deg": [0.0, 2.5, 5.0]}}
spec = RunSpec.from_dict(data)
if __name__ == "__main__":
with run_beam(spec, output_dir="beam-binned") as results:
print(results.beam_bins)
Exact mode details¶
Exact mode writes one line per sampled ion into TRIM.DAT (SRIM’s file of ions with
their energy, start position and direction) and runs SRIM on that file:
calculation: 1(quick Kinchin-Pease) runs SRIM calculation 4, andcalculation: 2(full cascades) runs SRIM calculation 5. Calculation 3 (sputtering) and the other values are refused with a distributed beam in exact mode (SpecError), so usebeam.mode: binnedfor those.The ion energy in
TRIM.INis the largest sampled energy (SRIM needs one value there; each ion’s own energy comes fromTRIM.DAT). The angle inTRIM.INis ignored.More than 99 999 ions do not fit one
TRIM.DATfile.run_beamsplits the beam into units of 99 999 ions and merges them.TRIM.from_spec(spec).run()refuses such a spec, so userun_beam.settings.descriptionmust be ASCII: it goes intoTRIM.DAT, which SRIM reads as ASCII. A spec with another character is refused when it is read.An in-place run (
srim_directory=) only deletes theTRIM.DATand thebeam/copies that pysrim2 wrote. An exact run there is refused if aTRIM.DATthat pysrim2 did not write is in the way (on Windows and macOS that includes SRIM’s own exampleTRIM.dat); run in an isolated copy (the default) instead.
Plotting¶
plot_beam(results, parameter) draws a parameter’s defined density with the sampled beam.
It needs matplotlib (pip install "pysrim2[plot]").
from srim.beam import plot_beam
with run_beam(spec, output_dir="beam-plot") as results: # the spec of the binned example above
ax = plot_beam(results, "energy_keV") # one bar per bin
ax.figure.savefig("beam-energy.png")
For an exact run the sampled ions are drawn as a density histogram, and the defined density (the clipped distribution) as a line. For a binned run each bin is a bar, with the probability per unit of the parameter, and the line is the defined density. A binned run has bins only for energy and angle, so other parameters raise an error. A parameter that is fixed in the run has nothing to plot and raises an error too.
Scans of beams¶
A scan can vary the shape parameters of a distribution, and the bin counts. Keys are
dotted, as for --set. The base is a run spec with a distribution (here the binned spec
above; Scan only defines the points, run_scan runs them):
from srim.scan import Scan
scan = Scan(
spec,
grid={
"ion.energy_keV.gaussian.sigma": [0.5, 1.0, 2.0],
"beam.bins.energy_keV": [5, 10],
},
extract=["implant_summary"],
ions=1000,
)
A binned point of a scan is a batched point: its units are the bins, and its folder records them (see Scans, section “Beam distributions in scans”). Exact points above 99 999 ions are split into units the same way.
Limits¶
One ion species per beam.
Parameters are independent (no correlated distributions).
Positions and non-uniform azimuths are exact-only.
Exact runs: at most 99 999 ions per SRIM run (larger beams are split), and an ASCII
settings.description.Binned runs: at most
beam.max_binsbins (2000 by default), and the bins are approximations of the continuous distribution.A histogram file is read when the spec is read, so the file must exist then.