run¶

The run layer: an analysis from a typed spec into an output directory.

An analysis is a Kind (sbmlsim.run.kinds): a pydantic Spec of its settings and the functions which run it. execute runs it whole, plan, count_units, compute_unit and merge run a splittable kind as units which other processes or machines compute (simrun) and a merge, with the same result as execute. A run writes only into its output directory, see sbmlsim.run.context for its files: run.json, spec.json, summary.json and the events in progress.jsonl.

The command line is python -m sbmlsim.run, see sbmlsim.run.cli:

python -m sbmlsim.run <kind> <spec> --out DIR [--workers N] [--resume]
    [--summary FILE]
python -m sbmlsim.run plan <kind> <spec> [-o FILE]
python -m sbmlsim.run unit <kind> <spec> <index> --out DIR
python -m sbmlsim.run merge <kind> <spec> --out DIR [--summary FILE]
python -m sbmlsim.run list <project> [--json] [--experiments]

--profile runs a command which writes into --out under the sampling profiler of python 3.15, see sbmlsim.run.profiling.

import sbmlsim does not import this package, and this package imports nothing of the analyses until it runs one.

RunContext `dataclass` ¶

RunContext(out, workers, resume, provenance, unit=None)

Where a run writes and what it may assume.

Attributes:

Name	Type	Description
`out`	`Path`	the output directory, which exists.
`workers`	`int \| None`	the number of processes the run may use: the given number, else every CPU of the quota (`available_cpus`) for a kind which uses several cores and 1 for one which does not, 1 for a unit.
`resume`	`bool`	whether the run continues an earlier one in `out`, so it keeps what exists, e.g. the files of the finished repeats.
`provenance`	`list[dict[str, Any]] \| None`	the provenance of the sources of the snapshot the run runs on, `None` outside of simrun.
`unit`	`int \| None`	the index of the unit a split run computes, `None` for a whole run or a merge.

progress_path `property` ¶

progress_path

The file of the events: progress.jsonl, of a unit progress/unit-<index>.jsonl.

write_json ¶

write_json(name, data)

Write a JSON file into the output atomically, see to_json.

Parameters:

Name	Type	Description	Default
`name`	`str`	the path of the file relative to `out`; its directories are created.	required
`data`	`Any`	the content.	required

Returns:

Type	Description
`Path`	The path of the file.

ConfigurationError ¶

Bases: Exception

A run is configured wrongly, e.g. an invalid spec or an output in use.

The command line exits with 4 for it.

Kind `dataclass` ¶

Kind(
    name,
    spec,
    run,
    plan=_identity,
    count_units=None,
    compute_unit=None,
    merge=None,
    inputs=(),
    uses_cores=True,
    cost_setting=None,
)

A kind of analysis: its spec and the functions which run it.

Attributes:

Name	Type	Description
`name`	`str`	the name of the kind, e.g. `fit`.
`spec`	`type[S]`	the class of its spec.
`run`	`Callable[[S, RunContext], dict[str, Any]]`	runs the whole analysis into the context and returns its summary.
`plan`	`Callable[[S], S]`	completes a spec into a planned spec (seeds, ids, `units`).
`count_units`	`Callable[[S], int] \| None`	the number of units of a planned spec, its `units` without.
`compute_unit`	`Callable[[S, int, RunContext], None] \| None`	computes one unit of a planned spec into the context.
`merge`	`Callable[[S, RunContext], dict[str, Any]] \| None`	merges the units into the result and returns the summary.
`inputs`	`tuple[str, ...]`	the fields of the spec, `Path \| None`, which are inputs, i.e. the outputs of other runs.
`uses_cores`	`bool`	whether the kind runs on several CPUs.
`cost_setting`	`str \| None`	the field of the spec a scheduler estimates the cost by.

splittable `property` ¶

splittable

Whether the kind runs as units and a merge.

OutInUse ¶

OutInUse(message, *, out, reason)

Bases: ConfigurationError

An output which a run may not run into, e.g. the output of another run.

The command line exits with 4 for it, as for every ConfigurationError.

Attributes:

Name	Type	Description
`out`		the output.
`reason`		why, one of `REASONS`: `not_a_directory`, `not_empty` (an output with files without `resume`), `no_record` (with `resume` an output with files and no `run.json`), `unreadable` (its `run.json` is not read) and `other_run` (the record of a run of another kind or spec).

Create the error.

Parameters:

Name	Type	Description	Default
`message`	`str`	the message for the user.	required
`out`	`Path`	the output.	required
`reason`	`str`	why the output is in use, one of `REASONS`.	required

Raises:

Type	Description
`ValueError`	for an unknown reason.

PlanMismatch ¶

Bases: ConfigurationError

A planned spec does not match what it resolves to, e.g. another scan.

Spec ¶

Bases: BaseModel

The settings of an analysis, the base of the spec of every kind.

A spec forbids unknown fields and is frozen, so its hash identifies a run.

is_name `classmethod` ¶

is_name(field, value)

Check whether the string of a field of path_strings is a name.

A name, e.g. the id of a fit, is not resolved against the directory of a spec file; no string is a name by default.

Parameters:

Name	Type	Description	Default
`field`	`str`	the name of the field.	required
`value`	`str`	its string.	required

Returns:

Type	Description
`bool`	Whether the string is a name and no path.

SplitSpec ¶

Bases: Spec

The spec of a kind which splits into units.

Attributes:

Name	Type	Description
`units`	`int \| None`	the number of units, set by the plan of the kind.

UnknownKind ¶

Bases: KeyError, ConfigurationError

A kind which is not registered.

MissingUnits ¶

MissingUnits(missing, n_units)

Bases: RuntimeError

A merge misses units which were not computed.

Attributes:

Name	Type	Description
`missing`		the indices of the missing units.
`n_units`		the number of units.

Name the missing units.

Parameters:

Name	Type	Description	Default
`missing`	`Sequence[int]`	the indices of the missing units.	required
`n_units`	`int`	the number of units.	required

spec_hash ¶

spec_hash(spec, exclude=())

Get the hash of a spec: the sha256 of its canonical JSON, sorted keys.

Parameters:

Name	Type	Description	Default
`spec`	`Spec`	the spec.	required
`exclude`	`Collection[str]`	the fields left out, the inputs of its kind (`Kind.inputs`), which are identified by their own provenance, so a run whose inputs are staged at another path is the same run.	`()`

Returns:

Type	Description
`str`	The hexadecimal digest.

get_kind ¶

get_kind(name)

Get a kind by its name or by a reference module:attribute.

Parameters:

Name	Type	Description	Default
`name`	`str`	the name of a registered kind, or `module:attribute` of a kind.	required

Returns:

Type	Description
`Kind[Any]`	The kind.

Raises:

Type	Description
`UnknownKind`	a `KeyError` and a `ConfigurationError` naming the kinds, for a name which is not registered.
`ConfigurationError`	for a reference to no kind.

register ¶

register(kind)

Register a kind by its name.

Parameters:

Name	Type	Description	Default
`kind`	`Kind[Any]`	the kind.	required

Raises:

Type	Description
`ValueError`	for a name which is registered, contains `:`, which references a kind, or is a command, see `RESERVED_NAMES`.

unit_blocks ¶

unit_blocks(n, max_units=MAX_UNITS)

Split items into blocks of consecutive items, one block per unit.

Every block has max(1, ceil(n / max_units)) items, the last one the rest, so there are at most max_units blocks.

Parameters:

Name	Type	Description	Default
`n`	`int`	the number of items.	required
`max_units`	`int`	the number of blocks at most.	`MAX_UNITS`

Returns:

Type	Description
`list[range]`	The blocks in the order of the items, none for no items.

Raises:

Type	Description
`ValueError`	for a negative `n` or `max_units` below 1.

execute ¶

execute(
    kind,
    spec,
    out,
    *,
    workers=None,
    resume=False,
    provenance=None,
    inputs=None,
    summary=None,
)

Run an analysis whole into an output directory.

The spec is validated, its inputs set and it is planned, unless the run resumes, which runs the planned spec of out/spec.json as it is, with the inputs given now. The run writes spec.json, run.json, summary.json and its events into out, see sbmlsim.run.context.

A resume is accepted for the spec the run in out was started with, its inputs left out (spec_hash), so the inputs may be staged at another path. A resume of a finished run runs it again, and its kind skips what exists, e.g. the finished repeats of a fit; progress.jsonl accumulates the events of every attempt.

Parameters:

Name	Type	Description	Default
`kind`	`str`	the name of the kind or `module:attribute` of a kind.	required
`spec`	`SpecLike`	the spec, its settings or a YAML or JSON file of them. The relative paths of a file are relative to the file; only the fields which are a `Path` or a list or tuple of them are resolved, not paths inside of other values.	required
`out`	`Path`	the output directory, created; it must be empty without `resume`.	required
`workers`	`int \| None`	the number of processes, every CPU of the quota without for a kind which uses several cores, else 1.	`None`
`resume`	`bool`	continue the run of the same spec in `out`.	`False`
`provenance`	`Path \| None`	the file of the provenance of the sources, the one of `SIMRUN_PROVENANCE` without.	`None`
`inputs`	`Mapping[str, Path] \| None`	the paths of the input fields of the spec by their name, resolved to absolute paths.	`None`
`summary`	`Path \| None`	a file the summary of a successful run is also written to, e.g. the summary of a task of simrun outside of `out`.	`None`

Returns:

Type	Description
`dict[str, Any]`	The summary of the run.

Raises:

Type	Description
`ConfigurationError`	for an unknown kind, a spec which is not read or invalid, an output which is not empty without `resume`, a resume of another spec and a provenance which is not read.

check_out ¶

check_out(kind, spec, out, *, resume=False, inputs=None)

Check that a run may run into an output, without running it.

The checks of execute before it runs: the kind and the spec are valid and the output may hold the run, an empty or missing output, or with resume the output of a run of the same kind and spec. Nothing is written, so a wrapper refuses before it starts.

Parameters:

Name	Type	Description	Default
`kind`	`str`	the name of the kind or `module:attribute` of a kind.	required
`spec`	`SpecLike`	the spec, its settings or a YAML or JSON file of them.	required
`out`	`Path`	the output directory.	required
`resume`	`bool`	whether the run would resume the run in `out`.	`False`
`inputs`	`Mapping[str, Path] \| None`	the paths of the input fields of the spec by their name.	`None`

Raises:

Type	Description
`OutInUse`	for an output the run may not run into; its `out` and `reason` say which and why.
`ConfigurationError`	for an unknown kind or a spec which is not read or invalid.

plan ¶

plan(kind, spec)

Plan a spec: the settings every unit of a split run computes alike.

Parameters:

Name	Type	Description	Default
`kind`	`str`	the name of the kind or `module:attribute` of a kind.	required
`spec`	`SpecLike`	the spec, its settings or a YAML or JSON file of them.	required

Returns:

Type	Description
`Spec`	The planned spec, e.g. with its seed and its `units`.

count_units ¶

count_units(kind, spec)

Count the units of a planned spec.

Parameters:

Name	Type	Description	Default
`kind`	`str`	the name of the kind or `module:attribute` of a kind.	required
`spec`	`SpecLike`	the planned spec.	required

Returns:

Type	Description
`int`	The number of units.

Raises:

Type	Description
`ConfigurationError`	for a kind which is not split and a spec which is not planned.

compute_unit ¶

compute_unit(kind, spec, index, out, *, inputs=None)

Compute one unit of a planned spec into an output directory, serially.

The units of a run compute into the same output, each of its own files, and a unit computed again writes the same files. The first unit writes the planned spec into spec.json, and a unit of another plan is refused, so the units of two plans do not mix. A unit writes its events into progress/unit-<index>.jsonl and no run.json, which the merge writes.

Parameters:

Name	Type	Description	Default
`kind`	`str`	the name of the kind or `module:attribute` of a kind.	required
`spec`	`SpecLike`	the planned spec.	required
`index`	`int`	the index of the unit, in `range(count_units(kind, spec))`.	required
`out`	`Path`	the output directory, created.	required
`inputs`	`Mapping[str, Path] \| None`	the paths of the input fields of the spec by their name.	`None`

Raises:

Type	Description
`ConfigurationError`	for a kind which is not split, a spec which is not planned and an index outside of the units.
`PlanMismatch`	if `out` holds the units of another planned spec.

merge ¶

merge(kind, spec, out, *, inputs=None, summary=None)

Merge the units of a planned spec in an output directory.

Writes spec.json, run.json and summary.json as execute does.

Parameters:

Name	Type	Description	Default
`kind`	`str`	the name of the kind or `module:attribute` of a kind.	required
`spec`	`SpecLike`	the planned spec.	required
`out`	`Path`	the output directory the units were computed into.	required
`inputs`	`Mapping[str, Path] \| None`	the paths of the input fields of the spec by their name.	`None`
`summary`	`Path \| None`	a file the summary of a successful merge is also written to.	`None`

Returns:

Type	Description
`dict[str, Any]`	The summary of the run.

Raises:

Type	Description
`ConfigurationError`	for a kind which is not split and a spec which is not planned.
`PlanMismatch`	if `out` holds the units of another planned spec.
`MissingUnits`	from the merge of a kind, naming the missing units.

list_analyses ¶

list_analyses(project, *, experiments=False)

List the analyses of a project, see sbmlsim.project.Project.analyses.

Parameters:

Name	Type	Description	Default
`project`	`str`	the project, `module:attribute`.	required
`experiments`	`bool`	also list the groups of the simulation experiments and every experiment, which imports the experiments.	`False`

Returns:

Type	Description
`list[dict[str, str]]`	One entry `{"kind", "name", "description"}` per analysis.

Raises:

Type	Description
`ConfigurationError`	for a project which is not loaded.

run¶

RunContext dataclass ¶

progress_path property ¶

write_json ¶

ConfigurationError ¶

Kind dataclass ¶

splittable property ¶

OutInUse ¶

PlanMismatch ¶

Spec ¶

is_name classmethod ¶

SplitSpec ¶

UnknownKind ¶

MissingUnits ¶

spec_hash ¶

get_kind ¶

register ¶

unit_blocks ¶

execute ¶

check_out ¶

plan ¶

count_units ¶

compute_unit ¶

merge ¶

list_analyses ¶

RunContext `dataclass` ¶

progress_path `property` ¶

Kind `dataclass` ¶

splittable `property` ¶

is_name `classmethod` ¶