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_amu is 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_deg and azimuth_deg are numbers or distributions; azimuth_deg (None when not given) and position (None when not given) make the beam distributed, see RunSpec.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_dir is the folder a relative histogram file is read from (the working directory when None); from_yaml() passes the folder of the run file.

classmethod from_yaml(path)

Read and validate a run.yaml. Raises SpecError.

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:, plus version).

Distributions are written as their YAML mappings. A histogram read from a file is written as its path; inline=True writes its content (and a Python function’s source) instead, for hashing. The azimuth_deg, position and beam keys 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, spec and provenance (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 file is read from base_dir (the working directory when None).

with_overrides(assignments)

A new spec with dotted.key=value assignments applied.

Values are converted by the schema (ion.energy_keV=30 is a float, number_ions=500 an 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.