srim.spec¶
Run specification: the run.yaml file.
A run spec holds everything needed to regenerate TRIM.IN; a run.yaml file
wraps it with informational provenance:
version: 1
spec:
ion: {symbol: B, energy_keV: 20.0, angle_deg: 7.0}
number_ions: 200
calculation: 1
seed: 12345
settings: {description: pysrim run, ranges: 1}
target:
- name: Au
thickness_nm: 100.0
density_g_cm3: 19.3
phase: 0
elements:
- {symbol: Au, stoich: 1.0, displacement_eV: 25.0, lattice_eV: 0.0, surface_eV: 3.0}
provenance: {pysrim2_version: ..., ...}
Units are part of the key names. pysrim’s own objects use eV for the ion energy and
Angstrom for layer widths; conversion is exact (1 nm = 10 A, 1 keV = 1000 eV) and done in
decimal arithmetic, so values with a short decimal form (100.0 nm, 20.0 keV)
give a TRIM.IN that is byte-identical to the one written for the equivalent
TRIM(...) object.
settings lists only the TRIMSettings values that differ from
their defaults, plus description and ranges which are always written. The angle
of incidence is ion.angle_deg and the random seed is seed (not in settings).
If a spec has no seed, one is picked when it is loaded, and TRIM.run records it.
A scan: section (see srim.scan.Scan) may sit next to spec:; a plain
run ignores it.
- class srim.spec.ElementSpec(symbol: str, stoich: float, displacement_eV: float = 25.0, lattice_eV: float = 0.0, surface_eV: float = 3.0, mass_amu: float | None = None)¶
One element of a layer.
mass_amuis only given when it differs from the element database (as in imported TRIM.IN files).
- class srim.spec.IonSpec(symbol: str, mass_amu: float, energy_keV: float | Shape, angle_deg: float | Shape = 0.0, azimuth_deg: float | Shape | None = None, position: PositionSpec | None = None)¶
The ion.
energy_keV,angle_degandazimuth_degare numbers or distributions;azimuth_deg(None when not given) andposition(None when not given) make the beam distributed, seeRunSpec.is_distributed.
- class srim.spec.LayerSpec(name: str, thickness_nm: float, density_g_cm3: float, phase: int = 0, elements: list = <factory>)¶
- class srim.spec.RunSpec(version: int, ion: IonSpec, target: list, settings: dict = <factory>, number_ions: int = 1000, calculation: int = 1, seed: int = 0, beam: BeamOptions | None = None)¶
A complete run description; see the module docstring for the file layout.
- classmethod from_dict(data, _prefix='', base_dir=None)¶
Build and validate a spec from plain data. Raises
SpecError.base_diris the folder a relative histogramfileis read from (the working directory when None);from_yaml()passes the folder of the run file.
- property is_distributed: bool¶
True when a beam parameter is a distribution, or azimuth or position is given.
Such a beam needs the beam runner (exact or binned mode); a plain spec is a single beam, as before distributions existed.
- to_dict(inline: bool = False)¶
The spec as plain Python data (what is stored under
spec:, plusversion).Distributions are written as their YAML mappings. A histogram read from a file is written as its path;
inline=Truewrites its content (and a Python function’s source) instead, for hashing. Theazimuth_deg,positionandbeamkeys appear only when they are set, so a plain spec has the same dict as before.
- to_yaml(path, provenance=None)¶
Write
run.yaml:version,specandprovenance(a dict, may be empty).Relative histogram files are checked against the folder of
path.
- validate(base_dir=None)¶
Raise
SpecError(naming the dotted key) if the spec is invalid.A relative histogram
fileis read frombase_dir(the working directory when None).
- with_overrides(assignments)¶
A new spec with
dotted.key=valueassignments applied.Values are converted by the schema (
ion.energy_keV=30is a float,number_ions=500an int). List items are addressed by index (target.0.thickness_nm=50).
- exception srim.spec.SpecError¶
A run spec is invalid; the message names the dotted key at fault.