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

depth_A

A

depth

ions_eV_per_A_per_ion

eV/A/ion

ionisation by the primary ions

recoils_eV_per_A_per_ion

eV/A/ion

ionisation by recoil atoms

vacancy (VACANCY.txt)

Vacancy production by depth.

Column

Unit

Meaning

depth_A

A

depth

knock_ons_per_A_per_ion

1/A/ion

knock-on atoms (ion-to-atom collisions)

vacancies_<el>_per_A_per_ion

1/A/ion

vacancies of element <el>, one column per element

novac (NOVAC.txt)

Replacement collisions. Typically absent for quick Kinchin-Pease calculations (calculation=1), present for full cascades.

Column

Unit

Meaning

depth_A

A

depth

replacements_per_A_per_ion

1/A/ion

replacement collisions

e2recoil (E2RECOIL.txt)

Energy transferred to recoil atoms by depth.

Column

Unit

Meaning

depth_A

A

depth

ions_eV_per_A_per_ion

eV/A/ion

energy lost by the primary ions to recoils

absorbed_<el>_eV_per_A_per_ion

eV/A/ion

energy absorbed by recoils of element <el>

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

depth_A

A

depth

ions_phonons_per_A_per_ion

Phonons/(A ion)

phonons from the primary ions

recoils_phonons_per_A_per_ion

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

depth_A

A

depth

ions_atoms_per_cm3_per_atoms_per_cm2

(atoms/cm3)/(atoms/cm2)

stopped ions

<el>_atoms_per_cm3_per_atoms_per_cm2

(atoms/cm3)/(atoms/cm2)

recoils of element <el> that came to rest

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

ion number

depth_A

A

final depth (x, along the beam)

y_A

A

final lateral position y

z_A

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

ion number

energy_keV

keV

ion energy at this point

depth_A

A

depth

y_A, z_A

A

lateral position

electronic_stopping_eV_per_A

eV/A

electronic stopping at this point

last_recoil_energy_eV

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

ion

number of the ion that caused the event

atomic_number

atomic number of the atom that left

energy_eV

eV

energy when leaving

depth_A

A

depth (see the note)

y_A, z_A

A

lateral position

cos_x, cos_y, cos_z

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 events

recoil events

ion

ion number

ion number

kind

"ion"

"recoil"

energy_keV

keV

ion energy

none

depth_A

A

depth of the collision

depth of the recoil

y_A, z_A

A

lateral position

lateral position

atom

symbol of the atom hit

symbol of the recoil

recoil_energy_eV

eV

energy given to the atom hit

recoil energy

target_displacements

displacements of the whole cascade of this collision

none

target_vacancies

vacancies of the cascade

none

target_replacements

replacements of the cascade

none

target_interstitials

interstitials of the cascade

none

atomic_number

none

Z of the recoil

electronic_stopping_eV_per_A

eV/A

electronic stopping Se

none

vacancy

none

1 if the recoil left a vacancy

replacement

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

n_ions

number of ions (rows)

mean_depth_A

projected range: mean of depth_A

straggle_depth_A

projected straggling: sample standard deviation (ddof=1) of depth_A

lateral_range_A

mean of `(

lateral_straggle_A

sample standard deviation of the signed y and z values taken together (ddof=1)

radial_range_A

mean of r = sqrt(y^2 + z^2)

radial_straggle_A

sample standard deviation of r

skewness, kurtosis

third and fourth standardised moments of depth_A (kurtosis is 3 for a Gaussian)

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

batch

every merged result

index of the unit (batch) the ion came from

beam_batch

binned beams

the beam batch the bin’s unit belongs to (a point’s ions are planned in beam batches: one without batch_ions or a precision target, several with them)

bin

binned beams

index of the bin (row of beam_bins)

bin_energy_keV

binned beams

the bin’s energy (the value the bin’s run used)

bin_angle_deg

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

bin index

energy_keV

keV

the bin’s energy (mean of the bin’s interval)

angle_deg

deg

the bin’s angle

energy_low_keV, energy_high_keV

keV

bin edges; NaN when the energy is fixed

angle_low_deg, angle_high_deg

deg

bin edges; NaN when the angle is fixed

probability

the bin’s probability under the defined distribution

n_ions

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

ion number (the global number for a merged result)

batch

unit index; only for a merged result (it comes after ion)

energy_keV

keV

ion energy

angle_deg

deg

angle of incidence, arccos(cos_x)

azimuth_deg

deg

direction around the axis, in [0, 360)

y_nm, z_nm, depth_nm

nm

start position

energy_eV, depth_A, y_A, z_A

eV, A

the same values in SRIM’s units, as written in TRIM.DAT

cos_x, cos_y, cos_z

direction cosines (cos_x > 0, into the target)

Exporting

Parquet, HDF5 and CSV export of all these tables is described in Export.