pycsamt.forward.maxwell.cache#

Content-addressed cache for canonical Maxwell forward results.

Entries are keyed by MaxwellProblem.problem_hash. Each result archive has a SHA-256 sidecar, is written by atomic replacement, and is validated against the requested problem when read. Lock files coordinate independent workers.

Classes

`CacheEntry`(key, archive_path, size_bytes, ...)	Describe one complete cache entry.
`CacheStatistics`(entry_count, total_bytes, ...)	Summarize the current on-disk cache state.
`MaxwellResultCache`(root, *[, ...])	Manage a validated, content-addressed result cache.

Exceptions

`CacheCorruptionError`	Indicate that a cached archive failed integrity validation.
`CacheLockTimeoutError`	Indicate that a cache-key lock could not be acquired in time.

exception pycsamt.forward.maxwell.cache.CacheCorruptionError[source]

Bases: RuntimeError

Indicate that a cached archive failed integrity validation.

Examples

>>> isinstance(CacheCorruptionError("bad checksum"), RuntimeError)
True

exception pycsamt.forward.maxwell.cache.CacheLockTimeoutError[source]

Bases: TimeoutError

Indicate that a cache-key lock could not be acquired in time.

Examples

>>> isinstance(CacheLockTimeoutError("busy"), TimeoutError)
True

class pycsamt.forward.maxwell.cache.CacheEntry(key, archive_path, size_bytes, modified_time_s)[source]

Bases: object

Describe one complete cache entry.

Parameters:

key (str) – Problem SHA-256 digest.
archive_path (pathlib.Path) – Result archive location.
size_bytes (int) – Combined archive and checksum size.
modified_time_s (float) – Archive modification time as Unix seconds.

Examples

>>> entry = CacheEntry("0" * 64, Path("result.npz"), 10, 1.0)
>>> entry.size_bytes
10

key: str

archive_path: Path

size_bytes: int

modified_time_s: float

property checksum_path: Path[source]

Return the SHA-256 sidecar path.

Returns:: Archive path with .sha256 appended.
Return type:: pathlib.Path

Examples

>>> entry = CacheEntry("0" * 64, Path("r.npz"), 0, 0)
>>> entry.checksum_path.name
'r.npz.sha256'

to_dict()[source]

Return JSON-compatible entry metadata.

Returns:: Key, path, size, and modification time.
Return type:: dict

Examples

>>> entry = CacheEntry("0" * 64, Path("r.npz"), 5, 2)
>>> entry.to_dict()["size_bytes"]
5

class pycsamt.forward.maxwell.cache.CacheStatistics(entry_count, total_bytes, orphan_count, corrupt_count)[source]

Bases: object

Summarize the current on-disk cache state.

Parameters:

entry_count (int) – Counts and storage for normal, incomplete, and quarantined files.
total_bytes (int) – Counts and storage for normal, incomplete, and quarantined files.
orphan_count (int) – Counts and storage for normal, incomplete, and quarantined files.
corrupt_count (int) – Counts and storage for normal, incomplete, and quarantined files.

Examples

>>> CacheStatistics(2, 100, 0, 1).entry_count
2

entry_count: int

total_bytes: int

orphan_count: int

corrupt_count: int

to_dict()[source]

Return JSON-compatible cache statistics.

Returns:: Entry, byte, orphan, and corruption counts.
Return type:: dict

Examples

>>> CacheStatistics(1, 20, 0, 0).to_dict()["total_bytes"]
20

class pycsamt.forward.maxwell.cache.MaxwellResultCache(root, *, lock_timeout_s=300.0, poll_interval_s=0.05, stale_lock_s=3600.0, quarantine_corrupt=True)[source]

Bases: object

Manage a validated, content-addressed result cache.

Parameters:

root (str or pathlib.Path) – Dedicated cache directory. It is created when absent.
lock_timeout_s (float, default=300) – Maximum wait for another worker holding the same problem key.
poll_interval_s (float, default=0.05) – Delay between lock acquisition attempts.
stale_lock_s (float, default=3600) – Age after which an abandoned lock can be removed.
quarantine_corrupt (bool, default=True) – Move corrupt files under root/corrupt. When false, reads raise CacheCorruptionError and leave the entry untouched.

Examples

>>> from tempfile import TemporaryDirectory
>>> with TemporaryDirectory() as directory:
...     cache = MaxwellResultCache(directory)
...     cache.statistics().entry_count
0

property root: Path[source]

Return the resolved cache root.

Returns:: Dedicated cache directory.
Return type:: pathlib.Path

Examples

The returned path is always absolute.

contains(problem)[source]

Return whether a complete entry exists for a problem.

Parameters:: problem (MaxwellProblem) – Problem whose content hash identifies the entry.
Returns:: True when both archive and checksum sidecar exist.
Return type:: bool

Examples

A newly created cache contains no problems.

get(problem)[source]

Load and validate a cached result.

Parameters:: problem (MaxwellProblem) – Exact problem expected by the caller.
Returns:: Valid result, or None when no complete entry exists. Corruption is quarantined and treated as a miss when configured.
Return type:: ForwardResult or None
Raises:: CacheCorruptionError – If validation fails and quarantine is disabled.

Examples

Cache misses return None rather than raising KeyError.

put(problem, result, *, overwrite=False)[source]

Validate and atomically store one result.

Parameters:

problem (MaxwellProblem) – Exact simulation input.
result (ForwardResult) – Canonical result matching problem.
overwrite (bool, default=False) – Replace an existing complete entry. Otherwise the validated existing entry is retained.

Returns:

Metadata for the stored or retained entry.

Return type:

CacheEntry

Examples

Invalid problem/result pairs are rejected before writing an archive.

get_or_solve(problem, backend)[source]

Return a hit or solve and cache one problem under a key lock.

Parameters:

problem (MaxwellProblem) – Simulation input and cache identity.
backend (MaxwellBackend) – Conforming backend used only after a cache miss.

Returns:

Valid cached or newly computed result.

Return type:

ForwardResult

Notes

The second read after locking prevents duplicate concurrent work.

Examples

Backend invocation is skipped whenever a validated hit exists.

entry(key)[source]

Return filesystem metadata for a complete entry.

Parameters:: key (str) – Problem SHA-256 digest.
Returns:: Entry paths, size, and modification time.
Return type:: CacheEntry
Raises:: KeyError – If archive or checksum sidecar is missing.

Examples

This method does not deserialize the result archive.

entries()[source]

Return complete entries sorted by problem key.

Returns:: Stable snapshot of complete cache entries.
Return type:: tuple of CacheEntry

Examples

An empty cache returns an empty tuple.

remove(problem)[source]

Remove one problem entry under its key lock.

Parameters:: problem (MaxwellProblem) – Exact problem identifying the entry.
Returns:: True when at least one entry file was removed.
Return type:: bool

Examples

Removing an absent problem is a no-op returning False.

prune(maximum_bytes)[source]

Remove oldest entries until storage is within a byte budget.

Parameters:: maximum_bytes (int) – Non-negative archive and checksum budget.
Returns:: Entries removed, oldest first.
Return type:: tuple of CacheEntry

Examples

prune(0) removes every complete entry but leaves infrastructure.

statistics()[source]

Inspect complete, orphaned, and quarantined cache files.

Returns:: Current cache counts and complete-entry storage.
Return type:: CacheStatistics

Examples

Statistics inspect metadata without deserializing archives.