srim.scan

Batched runs and scans built on srim.spec.RunSpec.

class srim.scan.BatchInfo(index: int, seed: int, n_ions: int, summary: dict | None = None, directory: str | None = None, columns: dict | None = None)

One batch: its index, seed, number of ions and summary (srim.analysis.implant_summary() of its RANGE_3D.txt; None without).

columns are extra columns of the merged per-ion tables, put right after batch in the order given (a binned beam’s unit has its beam batch, bin and bin value).

class srim.scan.MergedResults(parts, batches, spec=None, base_seed=None, keep_per_ion=True, tmpdir=None, beam_bins=None)

Results of run_batches(), with the surface of srim.output.Results.

Attributes ioniz, vacancy, novac, e2recoil, phonon, range (depth profiles: ion-count-weighted means of the batches, which must have identical depth bins) and range3d, exyz, backscat, transmit, sputter (per-ion tables: concatenated; ion is the global ion number, batch the batch index) each have .df and .metadata; an output that is absent is None. collision is streamed over the batches (collision.iter_events()). etorecoils and phonons are aliases of e2recoil and phonon.

batches lists the BatchInfo, seeds the seeds, spec the run spec (dict) with the total ion count and the base seed. Use close() or with to release the underlying results (and delete their run directories).

beam_bins

the bins of a binned beam (srim.beam.binned.bins_frame()), None otherwise

close()

Close every underlying result (deleting their run directories)

property n_ions

Total number of ions

property seeds

Seed of every batch, in order

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

As srim.output.Results.to_csv()

to_dataframes(include=None)

Tables as DataFrames; same selection rules as srim.output.Results.to_dataframes()

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

As srim.output.Results.to_hdf5()

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

As srim.output.Results.to_parquet()

class srim.scan.Precision(target: str, rel: float | None = None, abs: float | None = None, min_ions: int = 1000, max_ions: int = 100000, batch_ions: int = 1000)

Stop a point once target reaches a precision, within min_ions..``max_ions``.

Exactly one of rel (relative error of the value) and abs (absolute error) is given. batch_ions is the number of ions per batch. Raises SpecError naming the key at fault.

classmethod from_dict(data, prefix='precision.')

Build from a mapping; prefix is put in front of the key names in errors.

to_dict()

Plain data as stored under precision: in a scan section (unset keys omitted).

class srim.scan.Scan(base, grid=None, points=None, extract=None, ions=None, seed=None, batch_ions=None, keep_seed=False)

A base run spec, the parameters to vary and what to extract from each run.

With neither grid nor points the scan has the single point base. Keys number_ions and seed cannot be parameters. Every error names the dotted key (scan.grid.ion.energy_keV, scan.points[1]) as a SpecError.

Parameters:
  • base (srim.spec.RunSpec) – the run that every point starts from

  • grid (mapping, optional) – {dotted key: [values]}; the points are the cartesian product of the lists (the last key varies fastest)

  • points (list of mappings, or DataFrame, optional) – one row per point, all rows with the same keys. With grid as well, each row is combined with each grid combination; a key may be in one of them only.

  • extract (list, optional) – extractors: registered names, {name: params} mappings, or Python callables (written to run files as python: references, readable for module-level functions only). Default ["implant_summary"].

  • ions (int or Precision, optional) – ions per point, or a precision goal. Default: base.number_ions.

  • batch_ions (int, optional) – with a fixed ions: split each point into batches of this many ions (the last one may be smaller), each an independent run that the workers share. The point’s values and their <value>_err come from the batches (batch means), as for a precision target. Default None: one run per point. Not allowed with a precision target.

  • seed (int, optional) – base seed of the batches (None: the scan draws a random base seed and records it in scan.yaml)

  • keep_seed (bool, optional) – a one-point scan whose point runs with seed itself (no derived seed), so the run is the run of base with that seed (TRIM.IN as for TRIM.from_spec). It needs exactly one point, no batch_ions, no precision target, no binned beam and a seed. Default False.

classmethod from_yaml(path)

Read a run.yaml with a scan: section. Raises SpecError.

Extractors written as python:<module>:<qualname> are imported, which runs that module’s top-level code: only load scan files you trust.

property param_names: list[str]

The scanned keys, in the order of the points’ params

points() → list[ScanPoint]

All points, in order. Duplicate points are rejected when the scan is built (in __init__), not here.

to_dict() → dict

The scan: section as plain data (Python extractors as python: references).

to_yaml(path, provenance=None)

Write a run.yaml with the base spec and this scan: section.

Python extractors are written as python:<module>:<name> (see srim.scan.extract.reference()).

exception srim.scan.ScanBusy

Another scan is running in the scan folder (its lock is held).

class srim.scan.ScanPoint(index: int, params: dict, spec: RunSpec, id: str)

One point of a scan.

index is its position in the scan (grid order), params maps the normalised keys to the values of this point, spec is the run spec with those values applied and with number_ions set to the ion count of the point (Scan.ions, or the batch size for a Precision), and id is spec_hash() of spec (which does not depend on the ion count).

class srim.scan.ScanResult(scan: Scan, table: DataFrame)

The result of a scan: scan (the definition) and table (one row per point).

classmethod from_rows(scan: Scan, rows, base_dir=None) → ScanResult

Build the table from one dict per point (see the module docstring).

base_dir is the scan folder: an absolute path is stored relative to it (POSIX style), so exports hold no host paths. Raises SpecError for a row without a valid index or status, or an <x>_err column with no x, and ValueError for an absolute path that is not under base_dir.

plot(x=None, y=None, hue=True, ax=None)

Plot the extracted value y against the parameter x with error bars.

Defaults: x is the first scanned parameter, y the first extracted value and hue (one line per value) the first other scanned parameter; hue=False draws one line. Error bars come from <y>_err. ax is a matplotlib Axes (a new one is made if omitted). Needs matplotlib, which is imported here only.

to_csv(directory) → str

Write scan.csv and metadata.yaml (the scan and the base spec) to directory; returns the path of the CSV file.

to_hdf5(path, key='scan') → str

Write the table under key in an HDF5 file at path (needs pytables).

to_parquet(path) → str

Write the table to one Parquet file at path (needs pyarrow).

srim.scan.cache_key(spec: RunSpec, seed: int) → str

SHA-256 hex digest that identifies one SRIM run: its spec and its seed.

The digest covers the canonical YAML of spec.to_dict(inline=True), number_ions included, with its seed set to the given one, after a schema tag line. Beam distributions are covered in full: their definitions, histogram content (inline) and the source of Python-function distributions (srim.beam.spec.fingerprint()). Provenance (host, times, versions) is not part of it.

srim.scan.clear_cache(path) → int

Remove the entries of the cache at path; returns how many were removed.

Only a folder with a pysrim2 CACHEDIR.TAG is cleared; anything else raises ValueError and nothing is touched. Only what the cache itself makes is removed: shard folders named [0-9a-f]{2} holding entries named [0-9a-f]{64}, and the contents of tmp/. Any other item is left in place with a warning. An entry whose key is locked (a scan is computing or storing it) is kept. Lock files in locks/ are never removed (they are tiny and removing one could let a second writer lock a different file for the same key). The tag stays, so the folder is still recognised as a cache.

srim.scan.collect_slurm(scan_dir, *, cache=None) → ScanResult

Build the result of a prepared scan from its job folders, once the tasks are done.

Every point is read from its job folder: finished points are copied into points/<id>/ and their extractors run here; a point whose unit failed gets status failed with the first line of its error.log; a point whose unit has no outputs (not run yet, or still running) gets status missing with the error not run yet. The finished units are stored in the result cache (cache= as for srim.scan.run_scan(): default <scan folder>/cache, False for none), so a later local run of the same scan reuses them. The result is written to result/ as run_scan writes it.

Raises:
  • FileNotFoundError – when scan_dir has no scan.yaml

  • SpecError – for a precision scan, a scan without a base seed, or an extractor that cannot be imported (python: entries of scan.yaml)

  • ScanBusy – when another scan (or another collect) holds the scan folder’s lock

srim.scan.derive_seed(base_seed, batch_index)

Seed of batch batch_index for the base seed base_seed.

int(SHA-256(f"{base_seed}:{batch_index}")) of the first 8 bytes, modulo 2**31 - 1, plus one: a value in 1 .. 2**31 - 1. It only uses integer arithmetic and a fixed hash, so it is the same on every Python version and platform. Batch 0 does not reuse base_seed: all batches are derived the same way, which makes them independent of the number of batches.

srim.scan.prepare_slurm(scan: Scan, scan_dir, *, jobs=None) → Path

Write the job folders and submit.sbatch of scan into scan_dir.

Parameters:
  • scan (Scan) – a scan with a fixed ion count (ions= or the base spec’s number_ions)

  • scan_dir (path-like) – the scan folder (made if missing). It must not hold a prepared scan already.

  • jobs (int, optional) – number of job folders; the units (a point, or a batch of a point with batch_ions) are dealt round-robin into them. Default: one job per unit. At most one job per unit.

Returns:

the scan folder

Return type:

pathlib.Path

Raises:
  • SpecError – for a precision target, a bad jobs or two points with the same id

  • FileExistsError – when scan_dir already holds a prepared scan

srim.scan.read_scan_result(folder) → ScanResult

The ScanResult of a finished scan folder: scan.yaml and result/scan.csv.

The table is read back as ScanResult.to_csv() wrote it (the text columns stay text). Raises FileNotFoundError when either file is missing, and SpecError for a scan.yaml that is not a scan.

srim.scan.run_batches(spec, n_ions, batch_ions, seed=None, *, runner=None, parallel=None, keep_per_ion=True, pool=None)

Run n_ions ions as batches of batch_ions ions and merge the results.

Parameters:
  • spec (srim.spec.RunSpec) – the calculation; its number_ions and seed are replaced per batch

  • n_ions (int) – total ions and ions per batch; there are ceil(n_ions / batch_ions) batches, the last one smaller if needed

  • batch_ions (int) – total ions and ions per batch; there are ceil(n_ions / batch_ions) batches, the last one smaller if needed

  • seed (int, optional) – base seed; batch i runs with derive_seed(seed, i). Default: a random base seed (recorded in the result)

  • runner (callable, optional) – runner(spec) -> Results (anything with the output attributes and close()). Default: TRIM.from_spec(spec).run(); for tests or custom back ends. With parallel > 1 it is called from several threads and must be thread-safe.

  • parallel (int, optional) – number of batches running at once. The default runner uses a process pool, a custom runner a thread pool. Default: one after the other. When the first batch fails, batches that have not started are cancelled; running ones finish.

  • keep_per_ion (bool) – if False the per-ion tables (range3d, exyz …) and collision are not provided by the result (None); the batch summaries are still computed.

  • pool ("thread" or "process", optional) – pool type for parallel > 1 (default "process" without runner, else "thread"). A process pool needs a picklable runner (whose results have a directory that is copied) and, on macOS, Windows and Python 3.14 (spawn or forkserver), the calling script must be guarded by if __name__ == "__main__":.

Returns:

its tables’ metadata["num_ions"] is the requested total, whereas the tables’ own unique-ion counts can differ slightly (SRIM may omit a few ions).

Return type:

MergedResults

Raises:

Exception – the first failing batch’s exception, with a note naming the batch and its seed.

srim.scan.run_scan(scan, *, workers=None, backend='local', scan_dir=None, on_event=None, stop_event=None, pause_event=None, runner=None, cache=None, retries=1, image=None, runtime=None) → ScanResult

Run every point of scan and return the ScanResult.

Parameters:
  • scan (Scan) – the scan to run. Python extractors run in this process (they need not be picklable) and are written to scan.yaml as python:<module>:<name> references. With a Precision ions, each point runs in batches until its target is reached (see the module docstring).

  • workers (int, optional) – worker processes; default max(1, os.cpu_count() - 1), never more than the units of work the scan can have (points, or batches for precision targets).

  • backend (str) – "local" (the default) runs on this machine. "container" runs each unit in its own container of the pysrim2 image (pysrim2 run-job, see srim.scan.backends); the events and the result are the same. Slurm is not a back end of this function: see srim.scan.prepare_slurm().

  • scan_dir (path-like, optional) – the scan folder (made if missing). Default: a new ./scan-<UTC time> folder. An existing folder is reused: scan.yaml is overwritten and each point’s folder points/<id[:16]> is replaced by the new run.

  • on_event (callable, optional) – on_event(event) for every event (see srim.scan.events). Called in this process, from one thread, in order. An exception in it is logged as a warning and does not stop the scan.

  • stop_event (threading.Event, optional) – set it to stop the scan (see the module docstring)

  • pause_event (threading.Event, optional) – while it is set, no new unit starts (running ones finish); clear it to go on. Each change is reported as scan_paused.

  • runner (callable, optional) – runner(spec) -> Results (a picklable top-level function, as for srim.scan.run_batches()) in place of SRIM. Its results folder is copied to the point’s (or batch’s) folder and the runner owns its run directory. For tests and custom back ends. Default: TRIM.from_spec(spec).run(...) in a private run directory. Not allowed with backend="container".

  • cache (optional) – the result cache (see srim.scan.cache). None (the default): the folder named by $PYSRIM2_CACHE, else <scan_dir>/cache. False: no cache. A path: that folder (it must be empty or a pysrim2 cache). Runs found in the cache are not computed again; a rerun of a finished scan therefore computes nothing.

  • retries (int) – how often a failed unit (a point, or a batch) is run again before it is reported as failed (default 1)

  • image (str, optional) – container image for backend="container". Default: $PYSRIM2_IMAGE, else the image of this pysrim2 release (srim.installer.container.image_ref).

  • runtime (str, optional) – "podman" or "docker" for backend="container". Default: the first one found (srim.installer.container.find_runtime()).

Returns:

one row per point, also written to <scan_dir>/result/. Its scan has the base seed filled in when the scan had none.

Return type:

ScanResult

Raises:
  • ScanBusy – when another scan is running in scan_dir (nothing is started or written then)

  • ValueError – for an unknown backend, or runner= with the container back end

  • ContainerError – for backend="container" when no container runtime is found (before any worker starts)

  • FileNotFoundError – when there is no SRIM install and no runner is given (local back end)

srim.scan.spec_hash(spec: RunSpec) → str

SHA-256 hex digest of the canonical YAML of spec, without seed and number_ions.

Two specs with the same digest produce the same TRIM.IN apart from the seed and the ion count, so the digest (with a seed and an ion count) is a cache key. Beam distributions are covered as in srim.scan.cache.cache_key() (inline histograms, function source).