DataFrames¶
Every SRIM output that pysrim2 reads has a .df attribute: a
pandas.DataFrame with snake_case column names and the unit as a suffix
(depth_A, energy_eV, y_A, …). The units are SRIM’s own; nothing is
converted silently (A is Angstrom). The older attributes (.depth, .ions,
…) keep working unchanged.
from srim.output import Results
results = Results("test_files/1") # a folder with SRIM output files
results.ioniz.df.head()
results.ioniz.metadata # {'ion': 'Ni', 'energy_eV': 5000000.0, 'num_ions': 1000, 'source': ...}
dfs = results.to_dataframes() # dict: table name -> DataFrame, only the outputs that exist
Results.to_dataframes() returns the keys ioniz, vacancy, novac,
e2recoil, phonon, range, range3d, exyz, backscat, transmit and
sputter. An output whose file is missing is left out (for
example novac, which is typically absent for quick Kinchin-Pease runs). Because collision
can have millions of rows, it is not included by default; ask for it with
results.to_dataframes(include=["collision"]) (the same include= selection as the
exports; naming a table that is not available raises ValueError), or stream it (see
below).
Lazy loading¶
The depth profiles (ioniz, vacancy, novac, e2recoil, phonon, range)
are read when Results is created. The large per-ion files (range3d, exyz,
backscat, transmit, sputter, collision) are read on first access of the
attribute and cached: creating Results stays cheap, and a broken file raises
(or warns) at that access. A file changed after the first access is not re-read;
create a new Results. The attribute is None if the file is absent.
Depth profiles¶
TRIM normally writes these six files (novac is absent for Kinchin-Pease runs). All have depth_A as first column
(upper edge of the depth bin, Angstrom; the first bin starts at 0) and one row per depth bin. .metadata
holds ion (symbol), energy_eV, num_ions and source (the file read). num_ions
is SRIM’s ion count rounded to the nearest integer; the raw value SRIM writes (e.g.
59.93 for a run of 60 ions) is ions_calculated when the file has it.
Values are normalised per ion, so they do not depend on the number of ions.
The element columns are named after the elements of the target (Ni, Si,
C, …), in the order SRIM lists them. In a multi-element target the element
names come from the table header; if they cannot be read, pysrim2 warns and
falls back to 1, 2, … . The tables below show a single-element target
(Ni); <el> stands for an element symbol.
ioniz (IONIZ.txt)¶
Energy lost to electrons (ionisation) by depth.
Column |
Unit |
Meaning |
|---|---|---|
|
A |
depth |
|
eV/A/ion |
ionisation by the primary ions |
|
eV/A/ion |
ionisation by recoil atoms |
vacancy (VACANCY.txt)¶
Vacancy production by depth.
Column |
Unit |
Meaning |
|---|---|---|
|
A |
depth |
|
1/A/ion |
knock-on atoms (ion-to-atom collisions) |
|
1/A/ion |
vacancies of element |
novac (NOVAC.txt)¶
Replacement collisions. Typically absent for quick Kinchin-Pease
calculations (calculation=1), present for full cascades.
Column |
Unit |
Meaning |
|---|---|---|
|
A |
depth |
|
1/A/ion |
replacement collisions |
e2recoil (E2RECOIL.txt)¶
Energy transferred to recoil atoms by depth.
Column |
Unit |
Meaning |
|---|---|---|
|
A |
depth |
|
eV/A/ion |
energy lost by the primary ions to recoils |
|
eV/A/ion |
energy absorbed by recoils of element |
phonon (PHONON.txt)¶
Phonons (heat) produced by depth, in SRIM’s unit Phonons/(Angstrom-Ion) (SRIM’s plots treat them as energy).
Column |
Unit |
Meaning |
|---|---|---|
|
A |
depth |
|
Phonons/(A ion) |
phonons from the primary ions |
|
Phonons/(A ion) |
phonons from recoils |
range (RANGE.txt)¶
Final-position (implantation) profile of the ions, and of the recoils of each element.
Column |
Unit |
Meaning |
|---|---|---|
|
A |
depth |
|
(atoms/cm3)/(atoms/cm2) |
stopped ions |
|
(atoms/cm3)/(atoms/cm2) |
recoils of element |
Multiply by the fluence in atoms/cm2 to get a concentration in atoms/cm3.
Range.summary is a dict with the quantities SRIM prints in the header of
RANGE.txt: mean_depth_A (projected range), straggle_depth_A,
lateral_range_A, lateral_straggle_A, radial_range_A, radial_straggle_A,
skewness and kurtosis. SRIM prints them with 4 significant digits.
Per-ion tables¶
range3d (RANGE_3D.txt)¶
Final position of every ion. Written when ranges=1 in the settings (TRIM(..., ranges=1), or settings: {ranges: 1} in run.yaml; the default is 0).
The file is also found in the SRIM Outputs subfolder. .metadata: as above
with num_ions the number of rows (SRIM can leave out a few ions).
Column |
Unit |
Meaning |
|---|---|---|
|
ion number |
|
|
A |
final depth (x, along the beam) |
|
A |
final lateral position y |
|
A |
final lateral position z |
Pass max_rows=n to read only the first n rows (for example Range3D(folder, max_rows=n), or Backscat(folder, max_rows=n) for the event files); truncated is then True when rows were left out. The default reads every row.
exyz (EXYZ.txt)¶
Energy, position and stopping of each ion along its path, sampled every time
the ion has lost another exyz eV (the setting is the energy increment in eV;
0 switches the file off). .metadata has ion, energy_eV,
energy_interval_eV, num_ions and source. The parser is based on work by
philis-johan.
Column |
Unit |
Meaning |
|---|---|---|
|
ion number |
|
|
keV |
ion energy at this point |
|
A |
depth |
|
A |
lateral position |
|
eV/A |
electronic stopping at this point |
|
eV |
energy given to the last recoil |
backscat, transmit, sputter (BACKSCAT.txt, TRANSMIT.txt, SPUTTER.txt)¶
One row per atom leaving the target: backscattered ions (backscattered=1),
transmitted ions (transmit=1) and sputtered target atoms (sputtered=1;
sputtering needs a full cascade, calculation=2, to be meaningful). All three
have the same columns. .metadata has ion, energy_eV, num_events and
source. A file with only headers gives an empty frame; a zero-byte file gives
an empty frame and a warning.
Column |
Unit |
Meaning |
|---|---|---|
|
number of the ion that caused the event |
|
|
atomic number of the atom that left |
|
|
eV |
energy when leaving |
|
A |
depth (see the note) |
|
A |
lateral position |
|
direction cosines |
SRIM writes the depth of these files as an integer mantissa with an exponent
(5020011E-04 is 502.0011 A), and for backscattered ions with a minus sign
separated from the digits (- 6202433E-06 is -6.202433 A). pysrim2 decodes
both.
collision: the event stream¶
COLLISON.txt (setting collisions=1 for the ion’s own collisions, 2 to add
the recoils of full cascades) records every collision. It can be gigabytes, so
it is never read as a whole. Collision(directory) reads only the header;
iter_events() streams the file line by line, and .df builds the DataFrame
chunk-wise from that stream.
results = Results("test_files/SiC-C")
total = 0
for event in results.collision.iter_events(): # flat dicts, constant memory
if event["kind"] == "recoil" and event["vacancy"]:
total += 1
df = results.collision.df # everything; large files give large frames
One row/dict per event, in file order: each ion collision (kind="ion") is
followed by the recoils of its cascade (kind="recoil"). Fields that do not
apply to a kind are None in the dicts and NaN in the DataFrame.
Column |
Unit |
|
|
|---|---|---|---|
|
ion number |
ion number |
|
|
|
|
|
|
keV |
ion energy |
none |
|
A |
depth of the collision |
depth of the recoil |
|
A |
lateral position |
lateral position |
|
symbol of the atom hit |
symbol of the recoil |
|
|
eV |
energy given to the atom hit |
recoil energy |
|
displacements of the whole cascade of this collision |
none |
|
|
vacancies of the cascade |
none |
|
|
replacements of the cascade |
none |
|
|
interstitials of the cascade |
none |
|
|
none |
Z of the recoil |
|
|
eV/A |
electronic stopping Se |
none |
|
none |
1 if the recoil left a vacancy |
|
|
none |
1 if it was a replacement |
SRIM prints cascade positions (recoils) with fewer digits than the collision
lines (2718.E+00 against 27179.E-01).
Collision.metadata holds source. Per-ion access also works:
len(collision) is the number of ions and collision[i] a dict with the
collisions of ion i and its totals.
Skipped lines¶
SRIM sometimes writes recoil lines that belong to no collision (the cascade
header line was lost) and cascade summaries without a collision. They cannot be
attributed to an ion, so they are skipped, counted, and reported by one warning
per Collision after the first complete pass.
Collision.skipped_lines is the dict {"recoil": n, "summary": m} (counted
over the whole file; the first access streams the file once if needed).
Implantation summaries¶
Range.summary (parsed from the RANGE.txt header) is what SRIM reports.
srim.analysis.implant_summary(df) computes the same quantities from the
per-ion positions of range3d.df (depth_A, y_A, z_A):
from srim.analysis import implant_summary
implant_summary(results.range3d.df)
# {'n_ions': 996, 'mean_depth_A': ..., 'straggle_depth_A': ..., 'lateral_range_A': ...,
# 'lateral_straggle_A': ..., 'radial_range_A': ..., 'radial_straggle_A': ...,
# 'skewness': ..., 'kurtosis': ...}
Key |
Definition |
|---|---|
|
number of ions (rows) |
|
projected range: mean of |
|
projected straggling: sample standard deviation ( |
|
mean of `( |
|
sample standard deviation of the signed |
|
mean of |
|
sample standard deviation of |
|
third and fourth standardised moments of |
SRIM does not document how it computes the lateral straggling. The definition
above is inferred; on the reference case it agrees with the RANGE.txt header
to within about 1 % (146.4, 241.8 and 154.9 A against SRIM’s 145.9, 238.2 and
154.4 A for the depth, lateral and radial straggling), so do not expect exact
equality. The small differences also come from SRIM’s 4-digit header and from
ions missing in RANGE_3D.txt.
Note that the root-mean-square radial distance (about 342 A for the reference case) is a different quantity from SRIM’s lateral or radial straggling.
Beam distributions¶
These tables exist for distributed runs (see Beam distributions).
Merged per-ion tables¶
A result of several units (a batched exact beam, or a binned beam) is a MergedResults.
Its per-ion tables (range3d, exyz, backscat, transmit, sputter) are concatenated.
ion is the global ion number, and these columns come after it:
Column |
Present |
Meaning |
|---|---|---|
|
every merged result |
index of the unit (batch) the ion came from |
|
binned beams |
the beam batch the bin’s unit belongs to (a point’s ions are planned in beam batches: one without |
|
binned beams |
index of the bin (row of |
|
binned beams |
the bin’s energy (the value the bin’s run used) |
|
binned beams |
the bin’s angle |
beam_bins (binned beams)¶
results.beam_bins has one row per bin (the bins of srim.beam.binned.bins_frame). It is
also written as beam_bins.csv in the point folder.
Column |
Unit |
Meaning |
|---|---|---|
|
bin index |
|
|
keV |
the bin’s energy (mean of the bin’s interval) |
|
deg |
the bin’s angle |
|
keV |
bin edges; NaN when the energy is fixed |
|
deg |
bin edges; NaN when the angle is fixed |
|
the bin’s probability under the defined distribution |
|
|
ions run in this bin |
sampled_ions(results) (exact beams)¶
srim.beam.sampled_ions(results) reads the ions an exact run ran from its TRIM.DAT
file, one row per ion. The values are read back from the file (7 significant digits).
Column |
Unit |
Meaning |
|---|---|---|
|
ion number (the global number for a merged result) |
|
|
unit index; only for a merged result (it comes after |
|
|
keV |
ion energy |
|
deg |
angle of incidence, |
|
deg |
direction around the axis, in |
|
nm |
start position |
|
eV, A |
the same values in SRIM’s units, as written in |
|
direction cosines ( |
Exporting¶
Parquet, HDF5 and CSV export of all these tables is described in Export.