qdk_chemistry.remote.cache.tiered module

Tiered (layered) cache backend for QDK/Chemistry.

Chains multiple cache backends in priority order so that reads hit the fastest / closest tier first and writes propagate to every tier.

Typical setup pairs a fast local cache with a shared network cache:

cache = TieredCache([
    FolderCache("./cache"),             # L1 — fast local
    FolderCache("/shared/team_cache"),   # L2 — shared
])

Read path: Each tier is checked in order. On a hit in a slower tier the result is backfilled into all faster tiers so subsequent reads are local.
Write path: Data is written to every tier (write-through).

class qdk_chemistry.remote.cache.tiered.CacheBackend(*, is_shared=False)

Bases: ABC

Abstract base class for result caches.

Implementations must provide these operations:

get_job / put_job: persist Job metadata keyed by the deterministic run_hash.
get_data / put_data: content-addressed storage for DataClass objects. Primitives (floats, ints, …) are stored inline in the Job metadata and never touch these methods.
delete_job / delete_data: remove cached metadata or blobs.
clear: remove all entries from the cache.

Parameters:: is_shared (bool) – Set to True when the backing store is reachable from multiple machines (e.g. a network-mounted folder). Defaults to False.

name: str

__init__(*, is_shared=False)

Initialise the cache backend.

Parameters:: is_shared (bool)
Return type:: None

abstractmethod get_job(run_hash)

Retrieve job metadata by run_hash, or None on miss.

Return type:: Job | None
Parameters:: run_hash (str)

abstractmethod put_job(run_hash, job)

Store (or update) job metadata keyed by run_hash.

Return type:

None

Parameters:

run_hash (str)
job (Job)

abstractmethod get_data(content_hash)

Retrieve a DataClass object (or list) by its content hash, or None.

Return type:: DataClass | list | None
Parameters:: content_hash (str)

abstractmethod put_data(content_hash, data)

Store a DataClass object (or list) by its content hash.

Return type:

None

Parameters:

content_hash (str)
data (DataClass | list)

abstractmethod delete_job(run_hash)

Remove job metadata by run_hash. Returns True if it existed.

Return type:: bool
Parameters:: run_hash (str)

abstractmethod delete_data(content_hash)

Remove a DataClass blob by content hash. Returns True if it existed.

Return type:: bool
Parameters:: content_hash (str)

abstractmethod clear()

Remove all entries from the cache.

Return type:: None

property is_shared: bool: Whether this cache is reachable from both local and remote.

has_data(content_hash)

Check whether a DataClass blob exists without deserializing it.

The default implementation calls get_data() and checks for None. Backends that can answer this more cheaply (e.g. a HEAD request or a glob) should override.

Return type:: bool
Parameters:: content_hash (str)

to_config()

Return constructor kwargs sufficient to recreate this backend.

Subclasses should override this if they accept configuration (paths, URLs, credentials, etc.). The default returns an empty dict, which is only valid for backends that need no arguments.

Return type:: dict

class qdk_chemistry.remote.cache.tiered.TieredCache(tiers, **_kwargs)[source]

Bases: CacheBackend

Composite cache that layers multiple backends.

Parameters:

tiers (list[CacheBackend]) – Ordered list of cache backends, fastest first.
_kwargs (Any)

Raises:

ValueError – If tiers is empty.

Example:

from qdk_chemistry.remote.cache import FolderCache, TieredCache

cache = TieredCache([
    FolderCache("./local_cache"),
    FolderCache("/shared/team_cache"),
])
energy, wfn = scf.run(mol, 0, 1, "cc-pvdz", cache=cache)

name: str = 'tiered'

__init__(tiers, **_kwargs)[source]

Initialise with an ordered list of cache tiers.

Parameters:

tiers (list[CacheBackend])
_kwargs (Any)

property is_shared: bool[source]: A tiered cache is shared if any of its tiers is shared.

property tiers: list[CacheBackend][source]: Return a copy of the tier list.

get_job(run_hash)[source]

Check each tier in order; backfill faster tiers on a hit.

Return type:: Job | None
Parameters:: run_hash (str)

put_job(run_hash, job)[source]

Write-through to every tier.

Return type:

None

Parameters:

run_hash (str)
job (Job)

get_data(content_hash)[source]

Check each tier in order; backfill faster tiers on a hit.

Return type:: DataClass | list | None
Parameters:: content_hash (str)

put_data(content_hash, data)[source]

Write-through to every tier.

Return type:

None

Parameters:

content_hash (str)
data (DataClass | list)

has_data(content_hash)[source]

Return True if any tier contains the blob.

Return type:: bool
Parameters:: content_hash (str)

delete_job(run_hash)[source]

Remove from every tier. Returns True if any had it.

Return type:: bool
Parameters:: run_hash (str)

delete_data(content_hash)[source]

Remove from every tier. Returns True if any had it.

Return type:: bool
Parameters:: content_hash (str)

clear()[source]

Clear every tier.

Return type:: None