solprop.output.snapshots#

Immutable, verified checkpoints published while a propagation stays alive.

  • SnapshotController requests bounded local snapshots (snapshots= on a run): at a committed accepted endpoint the driver pauses, the optical file and the TDSE archive are closed, copied and checksummed, and the two writers reopen in the same session, keeping their advisory locks. SnapshotResult describes the last attempt.

  • read_snapshot() verifies a published generation (SnapshotInfo, SnapshotFiles) and restore_snapshot() restores it into a new writable directory.

Only closed files are copied; cloud transport and retirement belong to the caller. The manual page is docs/guide/results/output.md (“Periodic snapshots while computing”).

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]#

Latest attempt, or None before any request is serviced.

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.