solprop.output.snapshots#
Immutable, verified checkpoints published while a propagation stays alive.
SnapshotControllerrequests 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.SnapshotResultdescribes the last attempt.read_snapshot()verifies a published generation (SnapshotInfo,SnapshotFiles) andrestore_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
|
Verify a published generation's checksums, identities and accepted state. |
|
Restore a verified snapshot into a new writable working directory. |
Classes
|
Request bounded local snapshots at committed accepted steps. |
|
Locate a verified checkpoint's optical file and optional archive. |
|
Describe a verified immutable generation. |
|
Describe the most recent snapshot attempt. |
- class solprop.output.snapshots.SnapshotController(directory, *, interval_seconds=None, max_snapshots=3)[source]#
Bases:
objectRequest 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.
- class solprop.output.snapshots.SnapshotFiles(output, tdse_archive)[source]#
Bases:
objectLocate 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.
- tdse_archive: TDSEArchive | None#
- class solprop.output.snapshots.SnapshotInfo(directory, files, generation, z, n_saved, next_save_index, bytes_copied, configuration_hash)[source]#
Bases:
objectDescribe a verified immutable generation.
- Attributes:
- directorypathlib.Path
Published generation directory.
- filesSnapshotFiles
Read-only files; use
restore_snapshotbefore 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.
- files: SnapshotFiles#
- class solprop.output.snapshots.SnapshotResult(disposition, generation, z, bytes_copied, copy_seconds, pause_seconds, failure=None)[source]#
Bases:
objectDescribe 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.
- 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.