qdk_chemistry.remote.cache.folder module

Folder-based cache backend for QDK/Chemistry.

Stores job metadata and content-addressed data as plain files in a directory:

cache_dir/
    <run_hash>.job.json              # Job metadata
    <content_hash>.<type_name>.h5    # DataClass blobs
    <content_hash>.ndarray.npy       # NumPy arrays
    <content_hash>.list.json         # Supported nested lists

Primitives (floats, ints, strings, …) are stored inline in the Job JSON and never written as separate files.

qdk_chemistry.remote.cache.folder.CoreDataClass

alias of DataClass

qdk_chemistry.remote.cache.folder.instance_data_type_name(value)

Return a data-class instance’s wire-format identifier.

Parameters:

value (DataClass) – Data class instance whose identifier is requested.

Return type:

str

Returns:

The instance’s validated wire-format identifier.

Raises:

TypeError – If either naming method does not return a non-empty string, or if the class and instance identifiers disagree.

qdk_chemistry.remote.cache.folder.get_dataclass_type(type_name)

Return the registered DataClass for a wire type name, if available.

Return type:

type[DataClass] | None

Parameters:

type_name (str)

class qdk_chemistry.remote.cache.folder.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:

• run_hash (str)

• job (Job)

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

qdk_chemistry.remote.cache.folder.is_cacheable(value)

Return whether a value can be stored as a cache data entry.

Return type:

bool

Parameters:

value (Any)

class qdk_chemistry.remote.cache.folder.FolderCache(path, *, is_shared=False, **_kwargs)

Bases: CacheBackend

Content-addressed folder cache.

Parameters:

• path (str | Path) – Directory to use as the cache root. Created on first write.

• is_shared (bool) – True when this directory is a network mount reachable from remote compute nodes.

• _kwargs (Any)

name: str = 'folder'

__init__(path, *, is_shared=False, **_kwargs)

Initialise with the cache directory path.

Parameters:

• path (str | Path)

• is_shared (bool)

• _kwargs (Any)

get_job(run_hash)

Retrieve job metadata by run_hash, or None on miss.

Return type:

Job | None

Parameters:

run_hash (str)

put_job(run_hash, job)

Store (or update) job metadata keyed by run_hash.

Return type:

None

Parameters:

• run_hash (str)

• job (Job)

get_data(content_hash)

Retrieve cached data by its content hash, or None.

Return type:

Any | None

Parameters:

content_hash (str)

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

Store data by content hash unless shared storage is required but unavailable.

Return type:

None

Parameters:

• content_hash (str)

• data (Any)

• shared_only (bool)

has_data(content_hash, *, shared_only=False)

Fast existence check via glob (no deserialization).

Return type:

bool

Parameters:

• content_hash (str)

• shared_only (bool)

to_config()

Return kwargs to reconstruct this FolderCache.

Return type:

dict

delete_job(run_hash)

Remove job metadata by run_hash.

Only the .job.json file is deleted. Data blobs are left intact because they may be referenced by other jobs.

Return type:

bool

Parameters:

run_hash (str)

delete_data(content_hash)

Remove a DataClass blob (or list manifest and its items) by content hash.

Return type:

bool

Parameters:

content_hash (str)

clear()

Remove all cached jobs and data blobs.

Return type:

None