srim.output¶
Read output files of SRIM simulation
TODO: Read header information
- class srim.output.Backscat(directory, filename=None, max_rows=None)¶
BACKSCAT.txtThe kinetics of all backscattered ions (needsbackscattered=1)- Parameters:
directory (
str) – directory of calculationfilename (
str, optional) – filename. DefaultBACKSCAT.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_Ain an unusual format (an integer mantissa such as5020011E-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()anddfstream it line by line, andcollision[i]reads only the block of ioni.The file is decoded as
cp437and split at SRIM’s column separators (the box-drawing characters), not at white space.- Parameters:
directory (
str) – directory of calculationfilename (
str, optional) – filename for Collisions. DefaultCOLLISON.txt
Notes
len(collision)is the number of ions andcollision[i]adictwith the ion’scollisionsand its totals (displacements,avg_displacements,replacements,vacancies,interstitials,sputtered_atoms,transmitted_atoms, each also with anavg_variant).- property df¶
pandas.DataFrameofiter_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:ionion number (int) of the collision line
kind"ion"for a line of the collision table,"recoil"for a line of a cascade blockenergy_keVion: ion energy [keV]; recoil:
Nonedepth_Aion: depth; recoil:
X (A)of the cascade liney_A,z_Alateral position [Ang] (both kinds)
atomion: symbol of the atom hit; recoil: symbol of the recoil (from its atomic number)
recoil_energy_eVion: energy given to the atom hit; recoil:
Atom Energy(eV)target_displacementsion: totals of the
Summary of Above Cascadetarget_vacanciesline of that collision (in files without full
target_replacementscascades: the columns of the collision line);
target_interstitialsNoneif SRIM wrote none; recoil:Noneatomic_numberrecoil: Z; ion:
Noneelectronic_stopping_eV_per_Aion:
Se (eV/A); recoil:Nonevacancy,replacementrecoil: the
VacandReplflags (0 or 1); ion:NoneRecoil 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 perCollisionafter the first complete pass.Cascade positions are printed by SRIM with fewer digits than the collision lines (the depth
2718.E+00against27179.E-01).
- property metadata¶
dictwith thesourcefile 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:
dictwith the number of lines skipped as stray
- to_csv(path, chunk_rows=100000)¶
Stream all events into a CSV file,
chunk_rowsat a timeNot-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 fileNeeds
pip install pysrim2[parquet]. Events are writtenchunk_rowsat a time (one row group each), so memory does not grow with the file. The schema is fixed:ionint64,kindandatomstrings, all other columns float64; fields that do not apply to an event are null. The pysrim2 metadata is stored under the schema keypysrim2(seesrim.export).- Returns:
number of events written
- Return type:
int
- class srim.output.EXYZ(directory, filename='EXYZ.txt', max_rows=None)¶
EXYZ.txtEnergy of every ion along its path (needsexyz> 0 in TRIM)The
exyzsetting 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 calculationfilename (
str, optional) – filename for EXYZ. DefaultEXYZ.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
exyzsetting)
- 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.txtEnergy transfered to atoms through binary collision- Parameters:
directory (
str) – directory of calculationfilename (
str, optional) – filename for EnergyToRecoils. DefaultE2RECOIL.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.txtIonization by ions and depth. Includes header information about calculation- Parameters:
directory (
str) – directory of calculationfilename (
str, optional) – filename for Ioniz. DefaultIONIZ.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.txtTable of Replacement Collisions- Parameters:
directory (
str) – directory of calculationfilename (
str, optional) – filename for NoVacancy. DefaultNOVAC.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.txtDistribution of Phonons- Parameters:
directory (
str) – directory of calculationfilename (
str, optional) – filename for Phonons. DefaultPHONON.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.txtTable of the final distribution of the ions, and any recoiling target atoms- Parameters:
directory (
str) – directory of calculationfilename (
str, optional) – filename for Range. DefaultRANGE.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¶
dictof 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,skewnessandkurtosis(of the depth distribution). Values not present in the file arenan. Seesrim.analysis.implant_summary()for how to compute the same quantities fromsrim.output.Range3D.
- class srim.output.Range3D(directory, filename='RANGE_3D.txt', max_rows=None)¶
RANGE_3D.txtFinal position of every ion (needsranges=1in TRIM)- Parameters:
directory (
str) – directory of calculationfilename (
str, optional) – filename for Range3D. DefaultRANGE_3D.txtmax_rows (
int, optional) – read at most this many ions (the first ones). DefaultNone: all of them. Checktruncatedto 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¶
dictwithion(Nonefor an empty file),energy_eV,num_ionsandsource(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 whenResultsis 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:
IONIZ.txthandled bysrim.output.IonizVACANCY.txthandled bysrim.output.VacancyNOVAC.txthandled bysrim.output.NoVacancyE2RECOIL.txthandled bysrim.output.EnergyToRecoilsPHONON.txthandled bysrim.output.PhononsRANGE.txthandled bysrim.output.RangeRANGE_3D.txthandled bysrim.output.Range3D(range3disNoneif the file is absent and parsed on first access; theSRIM Outputssubfolder is searched too)EXYZ.txthandled bysrim.output.EXYZ,BACKSCAT.txtbysrim.output.Backscat,TRANSMIT.txtbysrim.output.Transmit,SPUTTER.txtbysrim.output.Sputter(exyz,backscat,transmit,sputter; eachNoneif the file is absent)COLLISON.txthandled bysrim.output.Collision(collision;Noneif absent; opening it reads only the header;collision.dfstreams the file)
- property backscat¶
srim.output.Backscat, parsed on first access;Noneif absent
- property collision¶
srim.output.Collision, created on first access;Noneif 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;Noneif absent
- property range3d¶
srim.output.Range3D, parsed on first access;Noneif absent
- spec¶
run spec (a dict, no provenance) of the run that made these results, set by
srim.srim.TRIM.run(); the defaultspecof theto_*exports
- property sputter¶
srim.output.Sputter, parsed on first access;Noneif absent
- to_csv(directory, spec=None, include=None, chunk_rows=100000)¶
Write the tables to
<directory>/<name>.csvplusmetadata.yamlmetadata.yamlholds the pysrim2 version, export time, the runspec(if given) and the.metadataof every table written.includeas into_parquet()(collisionis opt-in and written in chunks ofchunk_rows).- Returns:
table name -> path written
- Return type:
dict
- to_dataframes(include=None)¶
Tables as
pandas.DataFrameobjects- 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 exceptcollision(one row per ion collision and cascade recoil;COLLISON.txtcan be several GB), which is only loaded if named. Naming a table that is not available raisesValueError.- Returns:
table name -> DataFrame; outputs that are missing (e.g.
novacfor 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’HDFStorein table format (read back withpandas.read_hdf(path, "ioniz")). The metadata (seeto_parquet()) is a JSON string in the node attributepysrim2(store.get_storer("ioniz").attrs.pysrim2). An existing file is overwritten.collision(opt-in, seeto_parquet()) is appended in chunks ofchunk_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 tableNeeds
pip install pysrim2[parquet](pyarrow). The metadata of each table (its.metadata, the pysrim2 version, the runspecif given and the export time in UTC) is stored as JSON in the Parquet schema’s key-value metadata under the keypysrim2.- Parameters:
directory (
str) – created if neededspec (
srim.spec.RunSpecordict, optional) – run specification, stored in every file’s metadata (default:self.spec, set bysrim.srim.TRIM.run())include (iterable of
str, optional) – table names (keys ofto_dataframes()) to export; default all available tables exceptcollision, which can be huge and must be asked for (include=["collision"]); it is then streamed in chunks ofchunk_rowseventschunk_rows (
int) – events per chunk forcollision(default 100 000); memory use grows with it.sourcein 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;Noneif 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.txtThe kinetics of all target atoms sputtered from the target (needssputtered=1)- Parameters:
directory (
str) – directory of calculationfilename (
str, optional) – filename. DefaultSPUTTER.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_Ain an unusual format (an integer mantissa such as5020011E-04); the values are decoded to ordinary floats.
- class srim.output.Transmit(directory, filename=None, max_rows=None)¶
TRANSMIT.txtThe kinetics of all transmitted ions (needstransmit=1)- Parameters:
directory (
str) – directory of calculationfilename (
str, optional) – filename. DefaultTRANSMIT.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_Ain an unusual format (an integer mantissa such as5020011E-04); the values are decoded to ordinary floats.
- class srim.output.Vacancy(directory, filename='VACANCY.txt')¶
VACANCY.txtTable of the final distribution of vacancies vs depth- Parameters:
directory (
str) – directory of calculationfilename (
str, optional) – filename for Vacancy. DefaultVACANCY.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 becomesSi,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)