qdk_chemistry.remote.cache.folder module

Folder-based cache backend for QDK/Chemistry.

Stores job metadata and DataClass blobs as plain files in a directory:

cache_dir/
    <run_hash>.job.json              # Job metadata
    <content_hash>.<type_name>.h5    # DataClass blobs

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

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 / 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.folder.FolderCache(path, *, is_shared=False, **_kwargs)

Bases: CacheBackend

Content-addressed folder cache.

Parameters:

• path (str | pathlib.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 a DataClass object (or list) by its content hash, or None.

Return type:

DataClass | list | None

Parameters:

content_hash (str)

put_data(content_hash, data)

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

Return type:

None

Parameters:

• content_hash (str)

• data (DataClass | list)

has_data(content_hash)

Fast existence check via glob (no deserialization).

Return type:

bool

Parameters:

content_hash (str)

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