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 and put_job persist Job metadata by run hash.

  • get_data and put_data store supported values by content hash.

  • delete_job and delete_data remove cached metadata or blobs.

  • clear removes all cache entries.

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.

__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:
abstractmethod get_data(content_hash)

Retrieve cached data by its content hash, or None.

Return type:

Any | None

Parameters:

content_hash (str)

abstractmethod put_data(content_hash, data, *, shared_only=False)

Store data by content hash, optionally requiring shared storage.

Return type:

None

Parameters:

  • content_hash (str)

  • data (Any)

  • shared_only (bool)

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, *, shared_only=False)

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. When shared_only is true, non-shared backends always return False.

Return type:

bool

Parameters:

  • content_hash (str)

  • shared_only (bool)

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

for_remote()

Return the cache view reachable from a remote compute node.

Return type:

CacheBackend | None

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

Bases: CacheBackend

Composite cache that layers multiple backends.

Parameters:
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 | dict[str, Any]]) – Cache instances or serialized cache configurations, fastest first.

  • **_kwargs (Any) – Ignored compatibility configuration.

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.

for_remote()[source]

Return a cache containing only tiers reachable from remote nodes.

Return type:

CacheBackend | None

to_config()[source]

Return kwargs to reconstruct this TieredCache.

Return type:

dict

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:
get_data(content_hash)[source]

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

Return type:

Any | None

Parameters:

content_hash (str)

put_data(content_hash, data, *, shared_only=False)[source]

Write through to every eligible tier.

Return type:

None

Parameters:

  • content_hash (str)

  • data (Any)

  • shared_only (bool)

has_data(content_hash, *, shared_only=False)[source]

Return True if any eligible tier contains the blob.

Return type:

bool

Parameters:

  • content_hash (str)

  • shared_only (bool)

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