qdk_chemistry.remote.serialization module

File-based serialization for remote execution of QDK/Chemistry.

This module provides serialization for all QDK Chemistry data classes, enabling efficient transfer of algorithm inputs and outputs between local and remote systems. Each DataClass object is serialized to its own HDF5 file.

class qdk_chemistry.remote.serialization.FileSerializer

Bases: object

Handles file-based serialization of QDK Chemistry objects for remote transport.

Supported values are QDK Chemistry data classes, AlgorithmRef objects, NumPy arrays and scalars, Python primitives, and lists or tuples recursively containing supported values. Dictionaries are protocol structure rather than serializable values. Nested algorithm references remain supported through their tagged settings representation.

Each data class is serialized to its own .{type_name}.h5 file, and each NumPy array to its own .ndarray.npy file. Primitives and simple types are stored in a JSON manifest file.

Directory structure for inputs:

job_dir/
    manifest.json          # Metadata and primitive values
    <content_hash>.structure.h5
    <content_hash>.basis_set.h5
    ...

Directory structure for outputs:

job_dir/
    manifest.json          # Metadata
    <content_hash>.wavefunction.h5
    <content_hash>.ndarray.npy
    ...

classmethod register_dataclass(dataclass_type)

Register a DataClass subclass for deserialization.

Parameters:

dataclass_type (Type) – A DataClass loader with a static data type name.

Return type:

type

Returns:

The registered class (allows use as decorator).

classmethod is_dataclass(value)

Check if a value is a QDK Chemistry DataClass.

Return type:

bool

Parameters:

value (Any)

classmethod is_cacheable(value)

Check if a value can be stored in a shared cache.

Return type:

bool

Parameters:

value (Any)

classmethod serialize_value(directory, name, value, *, cache=None, content_hash=None, seed_cache=False)

Serialize a single value, returning manifest entry.

Parameters:

• directory (Path) – Directory to write files to.

• name (str) – Logical name used to derive opaque DataClass file names while traversing nested values.

• value (Any) – Value to serialize.

• cache (CacheBackend | None) – Shared cache backend used to replace existing blobs with "cached" manifest references.

• content_hash (str | None) – Optional hash used to check whether value is cached.

• seed_cache (bool) – Whether to write a cacheable value to shared storage before emitting a reference.

Return type:

dict[str, Any]

Returns:

Manifest entry describing the serialized value.

classmethod deserialize_value(directory, entry, *, cache=None)

Deserialize a value from a manifest entry.

Parameters:

• directory (Path) – Directory containing the files.

• entry (dict[str, Any]) – Manifest entry describing the value.

• cache (CacheBackend | None) – Optional cache backend used to resolve "cached" entries omitted from uploaded files.

Return type:

Any

Returns:

The deserialized value.

qdk_chemistry.remote.serialization.deserialize_inputs(directory, *, cache=None)

Deserialize algorithm inputs from a directory.

Parameters:

• directory (str | Path) – Directory containing the input files.

• cache (CacheBackend | None) – Optional cache backend used to resolve "cached" entries omitted from uploaded files.

Return type:

dict

Returns:

Deserialized inputs containing algorithm metadata, settings, arguments, and cache metadata.

qdk_chemistry.remote.serialization.deserialize_outputs(directory, *, cache=None)

Deserialize algorithm outputs from a directory.

Parameters:

• directory (str | Path) – Directory containing the output files.

• cache (CacheBackend | None) – Optional cache backend used to resolve or reuse cacheable result values.

Return type:

Any

Returns:

The deserialized result (tuple or single value).

qdk_chemistry.remote.serialization.get_input_files(directory)

Get list of all input files in a directory.

Parameters:

directory (str | Path) – Directory containing input files.

Return type:

list[Path]

Returns:

List of all files that should be uploaded.

qdk_chemistry.remote.serialization.get_output_files(directory)

Get list of all output files in a directory.

Parameters:

directory (str | Path) – Directory containing output files.

Return type:

list[Path]

Returns:

List of all files that should be downloaded.

qdk_chemistry.remote.serialization.get_serialized_file_names(entry)

Return every file referenced by a serialized manifest entry.

Parameters:

entry (dict[str, Any]) – Serialized value entry from an input or output manifest.

Return type:

list[str]

Returns:

Artifact file names in manifest order; primitive and cached entries contribute no names.

qdk_chemistry.remote.serialization.serialize_inputs(directory, args, kwargs, algorithm_type, algorithm_name, settings, *, run_hash=None, job_cache_key=None, owner=None, input_hashes=None, force_rerun=False, remote_cache=None, remote_cache_backend=None, remote_cache_transport=False)

Serialize algorithm inputs to a directory of files.

Parameters:

• directory (str | Path) – Directory to write files to.

• args (tuple) – Positional arguments for the algorithm.

• kwargs (dict) – Keyword arguments for the algorithm.

• algorithm_type (str) – Type of algorithm (e.g., “scf_solver”).

• algorithm_name (str) – Name of algorithm implementation.

• settings (dict) – Algorithm settings dictionary.

• run_hash (str | None) – Optional pre-computed algorithm run hash.

• job_cache_key (str | None) – Optional cache key for the remote job record.

• owner (dict[str, str | None] | None) – Optional workspace and project permitted to manage the job.

• input_hashes (dict[str, str] | None) – Optional dict mapping input names to their content hashes.

• force_rerun (bool) – Whether the compute node must skip its cache lookup.

• remote_cache (dict[str, Any] | None) – Optional coordinates passed to the remote cache factory, get_cache().

• remote_cache_backend (CacheBackend | None) – Shared cache backend; existing cacheable values become "cached" manifest references.

• remote_cache_transport (bool) – Whether to seed shared-cache misses and use the cache as artifact transport.

Return type:

list[Path]

Returns:

List of all files created (for upload).

qdk_chemistry.remote.serialization.serialize_outputs(directory, result, *, cache=None, cache_transport=False)

Serialize algorithm outputs to a directory.

Parameters:

• directory (str | Path) – Directory to write files to.

• result (Any) – The result from algorithm.run() (may be a tuple or single value).

• cache (CacheBackend | None) – Optional shared cache backend used for cacheable result values.

• cache_transport (bool) – Whether to seed shared-cache misses and use the cache as artifact transport.

Return type:

list[Path]

Returns:

List of all files created (for download).