solprop.output.snapshots#

Publish immutable, verified checkpoints while a propagation stays alive.

Only closed files are copied. The driver pauses at a committed accepted endpoint; the two writers retain their advisory locks and reopen in the same session. Cloud transport and retirement belong to the caller. See docs/guide/results/output.md.

Functions

`read_snapshot`(directory)	Verify a published generation's checksums, identities and accepted state.
`restore_snapshot`(directory, destination)	Restore a verified snapshot into a new writable working directory.

Classes

`SnapshotController`(directory, *[, ...])	Request bounded local snapshots at committed accepted steps.
`SnapshotFiles`(output, tdse_archive)	Locate a verified checkpoint's optical file and optional archive.
`SnapshotInfo`(directory, files, generation, ...)	Describe a verified immutable generation.
`SnapshotResult`(disposition, generation, z, ...)	Describe the most recent snapshot attempt.

class solprop.output.snapshots.SnapshotController(directory, *, interval_seconds=None, max_snapshots=3)[source]#

Bases: object

Request bounded local snapshots at committed accepted steps.

Parameters:

directorypathlib.Path or str: Store containing immutable generations. One active run owns a store.
interval_secondsfloat or None, optional: Positive finite monotonic-clock interval, s; None enables explicit requests only. The clock begins after preparation and restarts after publication.
max_snapshotsint, optional: Maximum generation count, including incomplete copies; a positive integer, three by default. A full store defers requests without stopping propagation.

Raises:

OutputError: If the interval or capacity is invalid.

Examples

>>> from solprop.output import SnapshotController
>>> snapshots = SnapshotController("snapshots", interval_seconds=1800)
>>> snapshots.request()  # serviced after the next committed accepted step
>>> snapshots.last_result is None
True

property last_result: SnapshotResult | None[source]#

Return the latest attempt, or None before any request is serviced.

Returns:

SnapshotResult or None: The result, including total pause time and bytes copied.

request()[source]#

Request a snapshot without I/O, waiting or acquiring a lock.

Suitable for a Python signal handler in the propagation thread. Multiple requests coalesce; one arriving during a copy remains pending afterwards.

class solprop.output.snapshots.SnapshotFiles(output, tdse_archive)[source]#

Bases: object

Locate a verified checkpoint’s optical file and optional archive.

Attributes:

outputpathlib.Path: Optical HDF5 file; restored files may be passed to Simulation.run.
tdse_archiveTDSEArchive or None: Matching archive request, preserving its output selection.

output: Path#

tdse_archive: TDSEArchive | None#

class solprop.output.snapshots.SnapshotInfo(directory, files, generation, z, n_saved, next_save_index, bytes_copied, configuration_hash)[source]#

Bases: object

Describe a verified immutable generation.

Attributes:

directorypathlib.Path: Published generation directory.
filesSnapshotFiles: Read-only files; use restore_snapshot before continuing them.
generationstr: Unique generation identifier.
zfloat: Accepted position, m.
n_savedint: Number of committed optical observations.
next_save_indexint: Next scheduled save beyond this endpoint.
bytes_copiedint: Sum of the optical and archive file sizes, bytes.
configuration_hashstr: Scientific configuration identity.

bytes_copied: int#

configuration_hash: str#

directory: Path#

files: SnapshotFiles#

generation: str#

n_saved: int#

next_save_index: int#

z: float#

class solprop.output.snapshots.SnapshotResult(disposition, generation, z, bytes_copied, copy_seconds, pause_seconds, failure=None)[source]#

Bases: object

Describe the most recent snapshot attempt.

Attributes:

disposition{‘published’, ‘deferred’, ‘failed’}: Whether a generation was published, capacity was full, or copying failed.
generationpathlib.Path or None: Published directory, if one exists, including after a reopening failure.
zfloat: Accepted checkpoint position, m.
bytes_copiedint: Successfully copied file bytes, excluding the manifest.
copy_secondsfloat: Time spent copying and verifying files, s.
pause_secondsfloat: Total time spent servicing this request, including reopening, s.
failurestr or None: Failure description, absent on success or capacity deferral.

bytes_copied: int#

copy_seconds: float#

disposition: Literal['published', 'deferred', 'failed']#

failure: str | None = None#

generation: Path | None#

pause_seconds: float#

z: float#

solprop.output.snapshots.read_snapshot(directory)[source]#

Verify a published generation’s checksums, identities and accepted state.

Parameters:

directorypathlib.Path or str: Completed generation containing manifest.json.

Returns:

SnapshotInfo: Verified read-only file locations and checkpoint identity.

Raises:

OutputError: If publication is incomplete, a checksum differs, or files disagree.

solprop.output.snapshots.restore_snapshot(directory, destination)[source]#

Restore a verified snapshot into a new writable working directory.

Parameters:

directorypathlib.Path or str: Immutable published generation; never modified.
destinationpathlib.Path or str: New directory, which must not exist. Files keep their relative layout.

Returns:

SnapshotFiles: Paths to pass to Simulation.run(..., resume=True) in a fresh process.

Raises:

OutputError: If verification fails, the destination exists, or restoration fails.