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 andsummary(srim.analysis.implant_summary()of itsRANGE_3D.txt;Nonewithout).columnsare extra columns of the merged per-ion tables, put right afterbatchin 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 ofsrim.output.Results.Attributes
ioniz,vacancy,novac,e2recoil,phonon,range(depth profiles: ion-count-weighted means of the batches, which must have identical depth bins) andrange3d,exyz,backscat,transmit,sputter(per-ion tables: concatenated;ionis the global ion number,batchthe batch index) each have.dfand.metadata; an output that is absent isNone.collisionis streamed over the batches (collision.iter_events()).etorecoilsandphononsare aliases ofe2recoilandphonon.batcheslists theBatchInfo,seedsthe seeds,specthe run spec (dict) with the total ion count and the base seed. Useclose()orwithto 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)¶
- 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)¶
- to_parquet(directory, spec=None, include=None, chunk_rows=100000)¶
- 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
targetreaches a precision, withinmin_ions..``max_ions``.Exactly one of
rel(relative error of the value) andabs(absolute error) is given.batch_ionsis the number of ions per batch. RaisesSpecErrornaming the key at fault.- classmethod from_dict(data, prefix='precision.')¶
Build from a mapping;
prefixis 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
gridnorpointsthe scan has the single pointbase. Keysnumber_ionsandseedcannot be parameters. Every error names the dotted key (scan.grid.ion.energy_keV,scan.points[1]) as aSpecError.- Parameters:
base (
srim.spec.RunSpec) – the run that every point starts fromgrid (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
gridas 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 aspython: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>_errcome from the batches (batch means), as for a precision target. DefaultNone: 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 inscan.yaml)keep_seed (bool, optional) – a one-point scan whose point runs with
seeditself (no derived seed), so the run is the run ofbasewith that seed (TRIM.INas forTRIM.from_spec). It needs exactly one point, nobatch_ions, no precision target, no binned beam and aseed. DefaultFalse.
- classmethod from_yaml(path)¶
Read a
run.yamlwith ascan:section. RaisesSpecError.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 aspython:references).
- to_yaml(path, provenance=None)¶
Write a
run.yamlwith the base spec and thisscan:section.Python extractors are written as
python:<module>:<name>(seesrim.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.
indexis its position in the scan (grid order),paramsmaps the normalised keys to the values of this point,specis the run spec with those values applied and withnumber_ionsset to the ion count of the point (Scan.ions, or the batch size for aPrecision), andidisspec_hash()ofspec(which does not depend on the ion count).
- class srim.scan.ScanResult(scan: Scan, table: DataFrame)¶
The result of a scan:
scan(the definition) andtable(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_diris the scan folder: an absolutepathis stored relative to it (POSIX style), so exports hold no host paths. RaisesSpecErrorfor a row without a validindexorstatus, or an<x>_errcolumn with nox, andValueErrorfor an absolute path that is not underbase_dir.
- plot(x=None, y=None, hue=True, ax=None)¶
Plot the extracted value
yagainst the parameterxwith error bars.Defaults:
xis the first scanned parameter,ythe first extracted value andhue(one line per value) the first other scanned parameter;hue=Falsedraws one line. Error bars come from<y>_err.axis a matplotlib Axes (a new one is made if omitted). Needs matplotlib, which is imported here only.
- to_csv(directory) str¶
Write
scan.csvandmetadata.yaml(the scan and the base spec) todirectory; returns the path of the CSV file.
- to_hdf5(path, key='scan') str¶
Write the table under
keyin an HDF5 file atpath(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_ionsincluded, with itsseedset 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.TAGis 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 oftmp/. 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 inlocks/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 statusfailedwith the first line of itserror.log; a point whose unit has no outputs (not run yet, or still running) gets statusmissingwith the errornot run yet. The finished units are stored in the result cache (cache=as forsrim.scan.run_scan(): default<scan folder>/cache,Falsefor none), so a later local run of the same scan reuses them. The result is written toresult/asrun_scanwrites it.
- srim.scan.derive_seed(base_seed, batch_index)¶
Seed of batch
batch_indexfor the base seedbase_seed.int(SHA-256(f"{base_seed}:{batch_index}"))of the first 8 bytes, modulo2**31 - 1, plus one: a value in1 .. 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 reusebase_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.sbatchofscanintoscan_dir.- Parameters:
scan (
Scan) – a scan with a fixed ion count (ions=or the base spec’snumber_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
jobsor two points with the same idFileExistsError – when
scan_diralready holds a prepared scan
- srim.scan.read_scan_result(folder) ScanResult¶
The
ScanResultof a finished scan folder:scan.yamlandresult/scan.csv.The table is read back as
ScanResult.to_csv()wrote it (the text columns stay text). RaisesFileNotFoundErrorwhen either file is missing, andSpecErrorfor ascan.yamlthat 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_ionsions as batches ofbatch_ionsions and merge the results.- Parameters:
spec (
srim.spec.RunSpec) – the calculation; itsnumber_ionsandseedare replaced per batchn_ions (
int) – total ions and ions per batch; there areceil(n_ions / batch_ions)batches, the last one smaller if neededbatch_ions (
int) – total ions and ions per batch; there areceil(n_ions / batch_ions)batches, the last one smaller if neededseed (
int, optional) – base seed; batchiruns withderive_seed(seed, i). Default: a random base seed (recorded in the result)runner (callable, optional) –
runner(spec) -> Results(anything with the output attributes andclose()). Default:TRIM.from_spec(spec).run(); for tests or custom back ends. Withparallel > 1it 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 customrunnera 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…) andcollisionare not provided by the result (None); the batch summaries are still computed.pool (
"thread"or"process", optional) – pool type forparallel > 1(default"process"withoutrunner, else"thread"). A process pool needs a picklablerunner(whose results have adirectorythat is copied) and, on macOS, Windows and Python 3.14 (spawn or forkserver), the calling script must be guarded byif __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:
- 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
scanand return theScanResult.- Parameters:
scan (
Scan) – the scan to run. Python extractors run in this process (they need not be picklable) and are written toscan.yamlaspython:<module>:<name>references. With aPrecisionions, each point runs in batches until its target is reached (see the module docstring).workers (
int, optional) – worker processes; defaultmax(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, seesrim.scan.backends); the events and the result are the same. Slurm is not a back end of this function: seesrim.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.yamlis overwritten and each point’s folderpoints/<id[:16]>is replaced by the new run.on_event (callable, optional) –
on_event(event)for every event (seesrim.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 asscan_paused.runner (callable, optional) –
runner(spec) -> Results(a picklable top-level function, as forsrim.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 withbackend="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 forbackend="container". Default:$PYSRIM2_IMAGE, else the image of this pysrim2 release (srim.installer.container.image_ref).runtime (
str, optional) –"podman"or"docker"forbackend="container". Default: the first one found (srim.installer.container.find_runtime()).
- Returns:
one row per point, also written to
<scan_dir>/result/. Itsscanhas the base seed filled in when the scan had none.- Return type:
- Raises:
ScanBusy – when another scan is running in
scan_dir(nothing is started or written then)ValueError – for an unknown
backend, orrunner=with the container back endContainerError – for
backend="container"when no container runtime is found (before any worker starts)FileNotFoundError – when there is no SRIM install and no
runneris given (local back end)
- srim.scan.spec_hash(spec: RunSpec) str¶
SHA-256 hex digest of the canonical YAML of
spec, withoutseedandnumber_ions.Two specs with the same digest produce the same
TRIM.INapart 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 insrim.scan.cache.cache_key()(inline histograms, function source).