conatus.runs.Run

class conatus.runs.Run(registry, name, *, tags=(), params=None, obj=None, parent=None, relation=None, status='provisional', telemetry=None, capacity=256, notes=None, key_parts=None, _record=None)

Bases: object

A registry run. Created live by conatus.runs.track() / conatus.runs.record() / solver.run(record=...), or read back by conatus.runs.get() / find.

Live methods: log() (series), result() (scalar results), save_field(), save_file(), attach() (a Problem / Plan / solver: numerics and explain()), certify() / retract(), close(). Read methods: params, results, series(), load_field(), file_path(), explain(), reproduce(), lineage().

Parameters:

• registry (Registry)

• name (str)

• tags (Iterable[str])

• params (Mapping[str, Any] | None)

• obj (Any)

• parent (Any)

• relation (str | None)

• status (str)

• telemetry (Any)

• capacity (int)

• notes (str | None)

• key_parts (dict | None)

• _record (dict | None)

classmethod load(registry, run_id)

Read-only view of a stored run.

Parameters:

• registry (Registry)

• run_id (str)

Return type:

Run

property name: str

property status: str

property state: str

property params: dict

property results: dict

property tags: list[str]

property parent: str | None

property path: Path

property cache_report: dict | None

attach(obj)

Record the problem hash, the numerical configuration (conatus.provenance.numerics) and the explain() text of a Problem, Plan or solver. The problem’s parameter values (IR Parameter values, overridden by discretize(params=...)) join the run parameters; a parameter declared twice with different values is refused.

Parameters:

obj (Any)

Return type:

Run

log(step=None, **scalars)

Append one row of series values (run.log(t=t, energy=E)); step is optional (the row number is always kept, so series logged together can be plotted against each other). In-memory only; written to data.h5 at close.

Parameters:

• step (int | None)

• scalars (Any)

Return type:

None

result(**values)

Scalar results (numbers, strings, booleans, complex): stored in run.json and indexed, so find(Nu__gt=...) works.

Parameters:

values (Any)

Return type:

None

save_field(name, array, *, compression, level=None, t=None, step=None)

Queue a copy of array for data.h5 (fields/<name>/<k>). compression has no default (None, ‘gzip’ or ‘lzf’, all lossless; level 0–9 for gzip) and is written in the dataset’s attributes. Returns False if the queue was full (dropped, counted).

Parameters:

• name (str)

• array (Any)

• compression (str | None)

• level (int | None)

• t (float | None)

• step (int | None)

Return type:

bool

save_file(path, name=None)

Queue a copy of a file into files/ (sha256 recorded). The copy is taken by the writer thread: a file changed right after this call may be copied changed.

Parameters:

• path (str | PathLike)

• name (str | None)

Return type:

bool

set_status(status, reason, evidence=None)

Change the status (history kept, never rewritten). reason is required.

Parameters:

• status (str)

• reason (str)

• evidence (Any)

Return type:

Run

certify(reason, evidence=None)

Mark the run certified (reason and optional evidence, e.g. residuals, recorded).

Parameters:

• reason (str)

• evidence (Any)

Return type:

Run

retract(reason)

Mark the run retracted (kept, never deleted; never reused by the cache).

Parameters:

reason (str)

Return type:

Run

close(state='completed', error=None, timeout=600.0)

Finish the run: series to data.h5, final run.json, index. Waits for the writer at most timeout s. Idempotent. Warns (RegistryWriteWarning) if anything was lost.

Parameters:

• state (str)

• error (str | None)

• timeout (float)

Return type:

Run

series(name, x=None)

{“row”, “step”, “value”} arrays of one series; with x (another series logged in the same rows, e.g. “t”), also “x” aligned on the rows both have (no interpolation).

Parameters:

• name (str)

• x (str | None)

Return type:

dict

load_field(name, index=-1)

One saved snapshot of a field (default: the last one).

Parameters:

• name (str)

• index (int)

Return type:

ndarray

file_path(name)

The attached file name of this run (a plain file name: no directory part, never “.” or “..”; security name=”../../x” read outside the run).

Parameters:

name (str)

Return type:

Path

refresh()

Re-read run.json (e.g. after another process changed the status).

Return type:

Run

lineage()

reproduce(solver=None, **kw)

Run this computation again and compare (see conatus.runs.reproduce()).

Parameters:

• solver (Any)

• kw (Any)

explain()

Return type:

str