solprop.output.scan#

A scan’s collected HDF5 file, to which one controller commits completed points.

  • PointResult carries one worker’s complete result, or its failure with the provenance available, to the single writer; validate_result() checks it before any committed data changes.

  • ScanWriter owns the collected file for one controller session, under the exclusive lock of solprop.output._scan_lock: points are staged and flushed before they are marked done, the staged groups are the recovery source, and the layout arrays and the concatenated periodic statistics are rebuilt from them at close.

  • read_point() and grid_values() read committed points, masking unfinished ones; solprop.processing.scans.ScanOutput is the user’s reader built on them.

The manual page is docs/guide/workflows/scans.md (“Retention, reductions and reading”).

Functions

grid_values(path, name)

Read a uniform result in global-index order with unfinished points masked.

read_point(path, index)

Read committed point data without exposing unfinished arrays.

validate_result(result)

Check the complete payload before changing committed data.

Classes

PointResult(index, status[, ...])

Carry a worker's complete result or failure to the single writer.

ScanWriter(path, scan, settings)

Own the collected file for one controller session.

class solprop.output.scan.PointResult(index, status, configuration_hash='', metadata_json='', arrays=<factory>, reductions=<factory>, error='', wall_time=0.0, n_steps=0, n_rejected=0, boundary_monitor=None, metadata_arrays=<factory>)[source]#

Bases: object

Carry a worker’s complete result or failure to the single writer.

Attributes:
indexint

Global scan index.

statusstr

Done, failed, skipped, conflict, or stopped: a point a stop flag stopped (SEP 41, S17), which is never committed, so a rerun computes it.

configuration_hashstr

Single-run configuration digest, empty if construction failed.

metadata_jsonstr

Complete run metadata, empty if construction failed.

metadata_arraysdict

The arrays the metadata names (solprop.output.metadata.RunMetadata.record_arrays()).

arraysdict

Named retained fields, statistics and reduction arrays.

reductionsdict

Reducer declarations with units, parameters and source provenance.

errorstr

Traceback or conflict explanation, empty on success.

wall_timefloat

Build and run wall time, s.

n_stepsint

Attempted propagation steps.

n_rejectedint

Rejected propagation steps.

boundary_monitorcollections.abc.Mapping or None

The point’s closing boundary-monitor record, without its per-plane rows (solprop.monitor.BoundaryMonitor.summary()), for a done or failed point that was watched; None otherwise.

arrays: Mapping[str, ndarray]#
boundary_monitor: Mapping[str, object] | None = None#
configuration_hash: str = ''#
error: str = ''#
index: int#
metadata_arrays: Mapping[str, ndarray]#
metadata_json: str = ''#
n_rejected: int = 0#
n_steps: int = 0#
reductions: Mapping[str, object]#
status: str#
wall_time: float = 0.0#
class solprop.output.scan.ScanWriter(path, scan, settings)[source]#

Bases: object

Own the collected file for one controller session.

Parameters:
pathpathlib.Path or str

Collected HDF5 path.

scanScan

Complete scan or selection; file identity uses the complete axes.

settingsmapping

Retention and reducer contracts; changed contracts refuse append.

close(*, consolidate=True)[source]#

Build layout arrays and CSR statistics, then close the writer.

A hard interruption before this point is readable from committed staging. Layouts already current – no point committed since they were built, as on a rerun with every point done – are kept rather than rebuilt: HDF5 does not reclaim the space of a deleted group, so each rebuild grows the file.

Parameters:
consolidatebool, optional

False closes an unchanged collection without rebuilding its layouts.

commit(result)[source]#

Validate and commit a result, publishing done after its payload.

Parameters:
resultPointResult

Complete worker result; failure payloads never touch numerical arrays.

Raises:
OutputError

If a cached configuration differs, a completed point would be demoted, or numerical results are not finite.

mark_running(index, now)[source]#

Publish a point claim before dispatch.

Parameters:
indexint

Global point index.

nowfloat

Current Unix time, s.

record_execution(executor, policy)[source]#

Append the controller policy and measured resource calculation.

Parameters:
executorstr

Executor class name.

policymapping

Effective thread, process and memory settings, including the probe.

record_recipe(record)[source]#

Record the recipe the scan was built from, unless one is recorded already.

The authored recipe, so that a scan reopens with its setup (SEP 41, S2); written once and never rewritten.

Parameters:
recordsolprop.output.records.RecipeRecord or None

The recipe; None, a scan from a script, records none.

state(index)[source]#

Read the durable scheduling state for a point.

Parameters:
indexint

Global point index.

Returns:
tuple

Status, configuration hash and last ownership update in Unix seconds.

solprop.output.scan.grid_values(path, name)[source]#

Read a uniform result in global-index order with unfinished points masked.

Parameters:
pathpathlib.Path

Collected scan file.

namestr

Flat point-array path.

Returns:
numpy.ma.MaskedArray

Array with leading global-point axis.

Raises:
ProcessingError

If no completed point has the result or its shapes differ.

solprop.output.scan.read_point(path, index)[source]#

Read committed point data without exposing unfinished arrays.

Parameters:
pathpathlib.Path

Scan file.

indexint

Global point index.

Returns:
collections.abc.Mapping

Status, traceback, metadata and flat array paths; for a done or failed point that was watched, its closing boundary_monitor record without the per-plane rows.

Raises:
ProcessingError

If the index is outside the scan.

OutputError

If the point’s run record declares an output schema other than this release’s.

solprop.output.scan.validate_result(result)[source]#

Check the complete payload before changing committed data.

Parameters:
resultPointResult

Complete point payload with status and provenance.