srim.output

Read output files of SRIM simulation

TODO: Read header information

class srim.output.Backscat(directory, filename=None, max_rows=None)

BACKSCAT.txt The kinetics of all backscattered ions (needs backscattered=1)

Parameters:
  • directory (str) – directory of calculation

  • filename (str, optional) – filename. Default BACKSCAT.txt

df
One row per atom (empty if there were none). Columns:
  • ion: number of the ion that caused the event (int)

  • atomic_number: Z of the atom (the backscattered ion) (int)

  • energy_eV: energy of the atom [eV]

  • depth_A: last depth X [Ang]

  • y_A, z_A: last lateral position [Ang]

  • cos_x, cos_y, cos_z: direction cosines of the final trajectory

Type:

pandas.DataFrame

Notes

SRIM writes depth_A in an unusual format (an integer mantissa such as 5020011E-04); the values are decoded to ordinary floats.

class srim.output.Collision(directory, filename='COLLISON.txt')

Reads the SRIM Collisions file.

This is the most important file in my opinion. It records every single collision and its energies. The file will get huge for simulations with many collisions, so it is never read as a whole: iter_events() and df stream it line by line, and collision[i] reads only the block of ion i.

The file is decoded as cp437 and split at SRIM’s column separators (the box-drawing characters), not at white space.

Parameters:
  • directory (str) – directory of calculation

  • filename (str, optional) – filename for Collisions. Default COLLISON.txt

Notes

len(collision) is the number of ions and collision[i] a dict with the ion’s collisions and its totals (displacements, avg_displacements, replacements, vacancies, interstitials, sputtered_atoms, transmitted_atoms, each also with an avg_ variant).

property df

pandas.DataFrame of iter_events(), one row per event, built chunk-wise from the stream (empty if the file has no collisions)

iter_events()

Generate every event in the file as a flat dict, streaming the file.

Each ion collision is yielded (kind="ion") followed by the recoils of its cascade (kind="recoil"), in file order. Keys, and the part of the file they come from:

ion

ion number (int) of the collision line

kind

"ion" for a line of the collision table, "recoil" for a line of a cascade block

energy_keV

ion: ion energy [keV]; recoil: None

depth_A

ion: depth; recoil: X (A) of the cascade line

y_A, z_A

lateral position [Ang] (both kinds)

atom

ion: symbol of the atom hit; recoil: symbol of the recoil (from its atomic number)

recoil_energy_eV

ion: energy given to the atom hit; recoil: Atom Energy(eV)

target_displacements

ion: totals of the Summary of Above Cascade

target_vacancies

line of that collision (in files without full

target_replacements

cascades: the columns of the collision line);

target_interstitials

None if SRIM wrote none; recoil: None

atomic_number

recoil: Z; ion: None

electronic_stopping_eV_per_A

ion: Se (eV/A); recoil: None

vacancy, replacement

recoil: the Vac and Repl flags (0 or 1); ion: None

Recoil lines that belong to no collision (SRIM writes some with recoil number 0 when the header line of a cascade is lost) and summary lines without a collision are skipped; their number is in skipped_lines, and a warning is issued once per Collision after the first complete pass.

Cascade positions are printed by SRIM with fewer digits than the collision lines (the depth 2718.E+00 against 27179.E-01).

property metadata

dict with the source file of the events

property skipped_lines

"recoil" (recoil lines outside a cascade) and "summary" (cascade summaries without a collision).

Counted over the whole file; the first access streams it once if iter_events() has not run to the end yet.

Type:

dict with the number of lines skipped as stray

to_csv(path, chunk_rows=100000)

Stream all events into a CSV file, chunk_rows at a time

Not-applicable fields are empty. Returns the number of events written.

to_parquet(path, chunk_rows=100000, spec=None)

Stream all events (see iter_events()) into a Parquet file

Needs pip install pysrim2[parquet]. Events are written chunk_rows at a time (one row group each), so memory does not grow with the file. The schema is fixed: ion int64, kind and atom strings, all other columns float64; fields that do not apply to an event are null. The pysrim2 metadata is stored under the schema key pysrim2 (see srim.export).

Returns:

number of events written

Return type:

int

class srim.output.EXYZ(directory, filename='EXYZ.txt', max_rows=None)

EXYZ.txt Energy of every ion along its path (needs exyz > 0 in TRIM)

The exyz setting is the energy increment [eV]: SRIM writes a line each time an ion has lost that much energy. Based on the parser by philis-johan.

Parameters:
  • directory (str) – directory of calculation

  • filename (str, optional) – filename for EXYZ. Default EXYZ.txt

df
One row per sampled point of an ion path. Columns:
  • ion: ion number (int)

  • energy_keV: ion energy [keV]

  • depth_A: depth X into the target [Ang]

  • y_A, z_A: lateral position [Ang]

  • electronic_stopping_eV_per_A: electronic stopping [eV/Ang]

  • last_recoil_energy_eV: energy lost to the last recoil [eV]

Type:

pandas.DataFrame

property depth

Depth [Ang] of the ion

property electronic_stop

Electronic stopping [eV/Ang] of the ion

property energy

Energy [keV] of the ion

property energy_interval

Energy increment [eV] between lines (the exyz setting)

property ion

Ion used in SRIM calculation

mass could be wrong

property ion_number

Ion number of each line

property metadata

ion, energy_eV, energy_interval_eV, num_ions, source

Type:

dict

property num_ions

Number of different ions in the file

property recoil_energy_loss

Energy [eV] lost to the last recoil

property y

Y position [Ang] of the ion

property z

Z position [Ang] of the ion

class srim.output.EnergyToRecoils(directory, filename='E2RECOIL.txt')

E2RECOIL.txt Energy transfered to atoms through binary collision

Parameters:
  • directory (str) – directory of calculation

  • filename (str, optional) – filename for EnergyToRecoils. Default E2RECOIL.txt

df
One row per depth bin. Columns:
  • depth_A: depth of bin [Ang]

  • ions_eV_per_A_per_ion: energy from ions [eV/(Angstrom-Ion)]

  • absorbed_<element>_eV_per_A_per_ion: energy absorbed by each target element [eV/(Angstrom-Ion)]

Type:

pandas.DataFrame

metadata

ion, energy_eV, num_ions, source

Type:

dict

property absorbed

Energy [eV/(Angstrom-Ion)] absorbed from collisions with Atom

TODO: fix terminology

property depth

Depth [Ang] of bins in SRIM Calculation

property ion

Ion used in SRIM calculation

mass could be wrong

property ions

Energy [eV/(Angstrom-Ion)] transfered to material through ion collisions

property num_ions

Number of Ions in SRIM simulation

class srim.output.Ioniz(directory, filename='IONIZ.txt')

IONIZ.txt Ionization by ions and depth. Includes header information about calculation

Parameters:
  • directory (str) – directory of calculation

  • filename (str, optional) – filename for Ioniz. Default IONIZ.txt

df
One row per depth bin. Columns:
  • depth_A: depth of bin [Ang]

  • ions_eV_per_A_per_ion: ionization by ions [eV/(Angstrom-Ion)]

  • recoils_eV_per_A_per_ion: ionization by recoils [eV/(Angstrom-Ion)]

Type:

pandas.DataFrame

metadata

ion, energy_eV, num_ions, source

Type:

dict

property depth

Depth [Ang] of bins in SRIM Calculation

property ion

Ion used in SRIM calculation

mass could be wrong

property ions

Ionization energy [eV/(Angstrom Ion)] lost to electronic stopping in incident ions

property num_ions

Number of Ions in SRIM simulation

property recoils

Ionization energy [eV/(Angstrom Ion)] lost to electronic stopping in recoil ions

class srim.output.NoVacancy(directory, filename='NOVAC.txt')

NOVAC.txt Table of Replacement Collisions

Parameters:
  • directory (str) – directory of calculation

  • filename (str, optional) – filename for NoVacancy. Default NOVAC.txt

df
One row per depth bin. Columns:
  • depth_A: depth of bin [Ang]

  • replacements_per_A_per_ion: replacement collisions [Number/(Angstrom-Ion)]

Type:

pandas.DataFrame

metadata

ion, energy_eV, num_ions, source

Type:

dict

property depth

Depth [Ang] of bins in SRIM Calculation

property ion

Ion used in SRIM calculation

mass could be wrong

property num_ions

Number of Ions in SRIM simulation

property number

Replacement Collisions [Number/(Angstrom-Ion)]

class srim.output.Phonons(directory, filename='PHONON.txt')

PHONON.txt Distribution of Phonons

Parameters:
  • directory (str) – directory of calculation

  • filename (str, optional) – filename for Phonons. Default PHONON.txt

df
One row per depth bin. Columns:
  • depth_A: depth of bin [Ang]

  • ions_phonons_per_A_per_ion: phonons from ions [Phonons/(Angstrom-Ion)]

  • recoils_phonons_per_A_per_ion: phonons from recoils [Phonons/(Angstrom-Ion)]

Type:

pandas.DataFrame

metadata

ion, energy_eV, num_ions, source

Type:

dict

property depth

Depth [Ang] of bins in SRIM Calculation

property ion

Ion used in SRIM calculation

mass could be wrong

property ions

Number of phonons [Phonons/(Angstrom Ion)] created from ions collisions

property num_ions

Number of Ions in SRIM simulation

property recoils

Number of phonons [Phonons/(Angstrom Ion)] created from recoils resulting from ion collisions

class srim.output.Range(directory, filename='RANGE.txt')

RANGE.txt Table of the final distribution of the ions, and any recoiling target atoms

Parameters:
  • directory (str) – directory of calculation

  • filename (str, optional) – filename for Range. Default RANGE.txt

df
One row per depth bin. Columns:
  • depth_A: depth of bin [Ang]

  • ions_atoms_per_cm3_per_atoms_per_cm2: final ion distribution [(Atoms/cm3)/(Atoms/cm2)]

  • <element>_atoms_per_cm3_per_atoms_per_cm2: target atoms of each element, in file order [(Atoms/cm3)/(Atoms/cm2)]

Type:

pandas.DataFrame

metadata

ion, energy_eV, num_ions, source

Type:

dict

property depth

Depth [Ang] of bins in SRIM Calculation

property elements

Per elements [(Atoms/cm3)/(Atoms/cm2)] distribution of each element

property ion

Ion used in SRIM calculation

mass could be wrong

property ions

Ion final distribution [(Atoms/cm3)/(Atoms/cm2)]

property num_ions

Number of Ions in SRIM simulation

property summary

dict of the statistics SRIM prints in the file header [Ang]

Keys mean_depth_A / straggle_depth_A (projected range and straggling), lateral_range_A / lateral_straggle_A, radial_range_A / radial_straggle_A, skewness and kurtosis (of the depth distribution). Values not present in the file are nan. See srim.analysis.implant_summary() for how to compute the same quantities from srim.output.Range3D.

class srim.output.Range3D(directory, filename='RANGE_3D.txt', max_rows=None)

RANGE_3D.txt Final position of every ion (needs ranges=1 in TRIM)

Parameters:
  • directory (str) – directory of calculation

  • filename (str, optional) – filename for Range3D. Default RANGE_3D.txt

  • max_rows (int, optional) – read at most this many ions (the first ones). Default None: all of them. Check truncated to see whether ions were left out.

df
One row per ion. Columns:
  • ion: ion number (int)

  • depth_A: final depth along the surface normal [Ang]

  • y_A: lateral position Y [Ang]

  • z_A: lateral position Z [Ang]

Type:

pandas.DataFrame

Notes

SRIM can leave the last line of the file incomplete; such a line is ignored. A zero-byte file gives an empty frame (same columns) and a warning, as for the event files.

property depth

Final depth [Ang] of each ion

property ion

Ion used in SRIM calculation

mass could be wrong

property metadata

dict with ion (None for an empty file), energy_eV, num_ions and source (file path)

property num_ions

Number of ion positions in the file

property y

Final lateral Y position [Ang] of each ion

property z

Final lateral Z position [Ang] of each ion

class srim.output.Results(directory)

Gathers all results from folder

Parameters:

directory (str) – directory to look for TRIM calculations

Notes

The files of the large per-ion outputs (RANGE_3D.txt, EXYZ.txt, BACKSCAT.txt, TRANSMIT.txt, SPUTTER.txt, COLLISON.txt) are read at first access of the attribute (results.range3d …), not when Results is created; the result is cached. A broken file therefore raises (or warns) then, and a file changed afterwards is not re-read.

Files that are looked for:
property backscat

srim.output.Backscat, parsed on first access; None if absent

property collision

srim.output.Collision, created on first access; None if absent

directory

folder the results were read from (for srim.srim.TRIM.run(), its run directory)

property exyz

srim.output.EXYZ, parsed on first access; None if absent

property range3d

srim.output.Range3D, parsed on first access; None if absent

spec

run spec (a dict, no provenance) of the run that made these results, set by srim.srim.TRIM.run(); the default spec of the to_* exports

property sputter

srim.output.Sputter, parsed on first access; None if absent

to_csv(directory, spec=None, include=None, chunk_rows=100000)

Write the tables to <directory>/<name>.csv plus metadata.yaml

metadata.yaml holds the pysrim2 version, export time, the run spec (if given) and the .metadata of every table written. include as in to_parquet() (collision is opt-in and written in chunks of chunk_rows).

Returns:

table name -> path written

Return type:

dict

to_dataframes(include=None)

Tables as pandas.DataFrame objects

Parameters:

include (iterable of str, optional) – table names to return: ioniz, vacancy, novac, e2recoil, phonon, range, range3d, exyz, backscat, transmit, sputter, collision. Default: every available table except collision (one row per ion collision and cascade recoil; COLLISON.txt can be several GB), which is only loaded if named. Naming a table that is not available raises ValueError.

Returns:

table name -> DataFrame; outputs that are missing (e.g. novac for Kinchin-Pease calculations) are omitted from the default selection.

Return type:

dict

to_hdf5(path, spec=None, include=None, chunk_rows=100000)

Write the tables to one HDF5 file, one key per table (/ioniz …)

Needs pip install pysrim2[hdf5] (PyTables). Written with pandas’ HDFStore in table format (read back with pandas.read_hdf(path, "ioniz")). The metadata (see to_parquet()) is a JSON string in the node attribute pysrim2 (store.get_storer("ioniz").attrs.pysrim2). An existing file is overwritten. collision (opt-in, see to_parquet()) is appended in chunks of chunk_rows.

Returns:

path

Return type:

str

to_parquet(directory, spec=None, include=None, chunk_rows=100000)

Write the tables to <directory>/<name>.parquet, one file per table

Needs pip install pysrim2[parquet] (pyarrow). The metadata of each table (its .metadata, the pysrim2 version, the run spec if given and the export time in UTC) is stored as JSON in the Parquet schema’s key-value metadata under the key pysrim2.

Parameters:
  • directory (str) – created if needed

  • spec (srim.spec.RunSpec or dict, optional) – run specification, stored in every file’s metadata (default: self.spec, set by srim.srim.TRIM.run())

  • include (iterable of str, optional) – table names (keys of to_dataframes()) to export; default all available tables except collision, which can be huge and must be asked for (include=["collision"]); it is then streamed in chunks of chunk_rows events

  • chunk_rows (int) – events per chunk for collision (default 100 000); memory use grows with it. source in the exported metadata is the file name only, not the full path.

Returns:

table name -> path written

Return type:

dict

property transmit

srim.output.Transmit, parsed on first access; None if absent

exception srim.output.SRIMOutputParseError

SRIM error reading output file

class srim.output.SRResults(directory, filename='SR_OUTPUT.txt')

Read SR_OUTPUT.txt file generated by pysrim SR.run()

property data

Structure of the returned value:

[
  <energy in keV>,
  <electronic stopping in <units> >,
  <nuclear stopping in <units> >,
  <projected range in um>,
  <longitudinal straggling in um>,
  <lateral straggling in um>
]
property ion

Structure of the returned value:

{
   'name': <e.g. Silicon>,
   'Z1': <int(atomic number)>,
   'A1': <float(atomic mass)>
}
property target

Structure of the returned value:

{
   'density g/cm3': <float>,
   'density atoms/cm3': <float>,
   'target composition': {
       <element 1 symbol>': {
           <int(Z)>,
           <float(stoichiometric percent)>,
           <float(mass percent)>
       },
       <element 2 symbol>': {...},
       ...
    }
}
class srim.output.Sputter(directory, filename=None, max_rows=None)

SPUTTER.txt The kinetics of all target atoms sputtered from the target (needs sputtered=1)

Parameters:
  • directory (str) – directory of calculation

  • filename (str, optional) – filename. Default SPUTTER.txt

df
One row per atom (empty if there were none). Columns:
  • ion: number of the ion that caused the event (int)

  • atomic_number: Z of the atom (the sputtered atom) (int)

  • energy_eV: energy of the atom [eV]

  • depth_A: last depth X [Ang]

  • y_A, z_A: last lateral position [Ang]

  • cos_x, cos_y, cos_z: direction cosines of the final trajectory

Type:

pandas.DataFrame

Notes

SRIM writes depth_A in an unusual format (an integer mantissa such as 5020011E-04); the values are decoded to ordinary floats.

class srim.output.Transmit(directory, filename=None, max_rows=None)

TRANSMIT.txt The kinetics of all transmitted ions (needs transmit=1)

Parameters:
  • directory (str) – directory of calculation

  • filename (str, optional) – filename. Default TRANSMIT.txt

df
One row per atom (empty if there were none). Columns:
  • ion: number of the ion that caused the event (int)

  • atomic_number: Z of the atom (the transmitted ion) (int)

  • energy_eV: energy of the atom [eV]

  • depth_A: last depth X [Ang]

  • y_A, z_A: last lateral position [Ang]

  • cos_x, cos_y, cos_z: direction cosines of the final trajectory

Type:

pandas.DataFrame

Notes

SRIM writes depth_A in an unusual format (an integer mantissa such as 5020011E-04); the values are decoded to ordinary floats.

class srim.output.Vacancy(directory, filename='VACANCY.txt')

VACANCY.txt Table of the final distribution of vacancies vs depth

Parameters:
  • directory (str) – directory of calculation

  • filename (str, optional) – filename for Vacancy. Default VACANCY.txt

df
One row per depth bin. Columns:
  • depth_A: depth of bin [Ang]

  • knock_ons_per_A_per_ion: primary knock-ons by the ion [knock-ons/(Angstrom-Ion)]

  • vacancies_<element>_per_A_per_ion: vacancies of each target element, in file order (a repeated element becomes Si, Si_2, …)

Type:

pandas.DataFrame

metadata

ion, energy_eV, num_ions, source

Type:

dict

property depth

Depth [Ang] of bins in SRIM Calculation

property ion

Ion used in SRIM calculation

mass could be wrong

property knock_ons

Primary knock-ons produced by the ion [knock-ons/(Angstrom-Ion)]

property num_ions

Number of Ions in SRIM simulation

property vacancies

Vacancies [Vacancies/(Angstrom-Ion)] produced of element in layer

srim.output.buffered_findall(filename, string, start=0)

A method of reading a file in buffered pieces (needed for HUGE files)