qdk_chemistry.remote.proxy module

Remote execution and caching for QDK/Chemistry algorithms.

class qdk_chemistry.remote.proxy.Job(*, job_id, backend, backend_config, backend_state, algorithm_info=None, status='submitted', submitted_at=None, file_path=None, run_hash=None, input_hashes=None, output_hashes=None, output_is_tuple=None, owner=None)

Bases: object

Persistent handle for a cached computation.

Instances serialise to a JSON file on disk, making them the canonical record of a cached algorithm run.

Parameters:
job_id

Short unique identifier for this job.

backend

Registered backend name (e.g. "local").

backend_config

Dict of configuration that was passed to the backend constructor (pool, gpus, host, …). Stored so the backend can be re-created from scratch.

backend_state

Opaque dict written by the backend during submit. Contains whatever the backend needs to poll / cancel / fetch (operation IDs, remote paths, PIDs, …).

algorithm_info

Dict with type, name, settings of the algorithm that was submitted.

status

Last-known status string.

submitted_at

ISO-8601 timestamp of submission.

file_path

Path to the job file on disk (None if not persisted yet).

run_hash

Deterministic hash of the algorithm, settings, and inputs. Used for cache lookups. None if not computed.

input_hashes

Per-item content hashes of the submitted inputs, keyed by namespaced argument name (e.g. "args.arg_0", "kwargs.charge"). None if not recorded.

output_hashes

Per-item result descriptors. Each entry is a dict with "hash" and "type" keys. Primitives also carry a "value" key so they can be reconstructed without a cache backend. Populated when results are fetched. None until results are retrieved.

output_is_tuple

Whether the retrieved result is a tuple. None until results are retrieved.

owner

Workspace and project permitted to manage the job through MCP. None for unowned SDK jobs.

__init__(*, job_id, backend, backend_config, backend_state, algorithm_info=None, status='submitted', submitted_at=None, file_path=None, run_hash=None, input_hashes=None, output_hashes=None, output_is_tuple=None, owner=None)

Initialise a Job from its constituent parts.

Parameters:

  • job_id (str) – Unique identifier assigned by the backend.

  • backend (str) – Registered backend name.

  • backend_config (dict[str, Any]) – Configuration used to reconstruct the backend.

  • backend_state (dict[str, Any]) – Persisted backend-specific job state.

  • algorithm_info (dict[str, Any] | None) – Submitted algorithm type, name, and settings.

  • status (str) – Initial job status.

  • submitted_at (str | None) – ISO-8601 submission timestamp.

  • file_path (str | Path | None) – Optional path for the persisted job record.

  • run_hash (str | None) – Deterministic hash used for cache lookup.

  • input_hashes (dict[str, str] | None) – Content hashes for submitted inputs.

  • output_hashes (list[dict[str, Any]] | None) – Content-hash descriptors for retrieved outputs.

  • output_is_tuple (bool | None) – Whether the retrieved result is a tuple.

  • owner (dict[str, str | None] | None) – Workspace and project permitted to manage this job through MCP.

to_dict()

Return a JSON-safe dictionary representing this job.

Return type:

dict[str, Any]

save(path=None)

Write the job file to disk atomically.

Parameters:

path (str | Path | None) – Explicit file path. If None, uses file_path (which must have been set earlier, e.g. via job_dir at submit time).

Return type:

Path

Returns:

The path the file was written to.

Raises:

ValueError – If no path is available.

classmethod load(path)

Reconstruct a Job from a previously saved file.

Parameters:

path (str | Path) – Path to a *.job.json file.

Return type:

Job

Returns:

A fully re-hydrated Job.

classmethod discover(directory)

Find all job files in a directory.

Parameters:

directory (str | Path) – Folder to scan (non-recursively) for *.job.json files.

Return type:

list[Job]

Returns:

List of Job instances, sorted by submitted_at (oldest first).

attach_backend(backend)

Associate this in-memory job with its submitting backend.

Return type:

None

Parameters:

backend (RemoteBackend)

detach_backend()

Remove the non-persistent backend association.

Return type:

None

check()

Query the backend, persist the latest status, and return it.

Return type:

JobStatus

cancel()

Cancel the backend job and persist its canceled status.

Return type:

None

fetch(local_dir=None, *, cleanup=False)

Download and persist results, then optionally remove backend artifacts.

Parameters:

  • local_dir (str | Path | None) – Optional directory to download result files into.

  • cleanup (bool) – Whether to remove backend job artifacts after successful retrieval and persistence.

Return type:

Any

Returns:

The deserialized algorithm results.

cleanup()

Remove backend artifacts for this terminal job.

Repeated cleanup is safe when supported by the backend.

Raises:

RuntimeError – If the job has not reached a terminal state.

Return type:

None

wait()

Block until the job reaches a terminal state.

Return type:

JobStatus

Returns:

The final status reported by the backend.

Raises:

TimeoutError – If the configured timeout expires before completion.

property is_terminal: bool

Whether the job has reached a final state.

property is_successful: bool

Whether the job completed successfully.

qdk_chemistry.remote.proxy.submit(algorithm, *args, remote, job_dir=None, **kwargs)[source]

Submit an algorithm for remote execution without blocking.

Parameters:

  • algorithm (Any) – Algorithm-like object to execute remotely.

  • *args (Any) – Positional arguments for the algorithm.

  • remote (Any) – Remote backend name or connected backend instance.

  • job_dir (str | Path | None) – Optional directory where the job record is saved.

  • **kwargs (Any) – Keyword arguments for the algorithm.

Return type:

Job

Returns:

A job handle that can be checked, canceled, fetched, or waited on.

qdk_chemistry.remote.proxy.run(algorithm, *args, cache=None, remote=None, force_rerun=False, _on_job_submitted=None, _owner=None, **kwargs)[source]

Execute any algorithm with optional caching and remote backend.

Works with both Python and C++ algorithm implementations — anything with run(), hash(), type_name(), name(), and settings() methods.

On a cache hit the result is returned immediately. On a miss the algorithm is executed (locally or via remote) and the result is stored. If a previous remote submission is still in-flight, polling resumes automatically — no duplicate submission.

Parameters:

  • algorithm (Any) – Any algorithm instance (from create(...)).

  • *args (Any) – Positional arguments for algorithm.run().

  • cache (Any) – Cache backend — a CacheBackend, a path (str / Path → FolderCache), or None. For remote execution, complete caller-side records are cache hits whether or not the backend is shared. Shared backends are also used by the compute node as transport. A TieredCache can combine local and shared backends.

  • remote (Any) – Remote backend name or instance, or None for local.

  • force_rerun (bool) – If True, skip the cache lookup and re-execute, overwriting any previously cached result.

  • _on_job_submitted (Callable[[Job], None] | None) – Internal callback invoked after a remote job handle is persisted to the local cache.

  • _owner (dict[str, str | None] | None) – Internal workspace and project ownership for MCP-managed jobs.

  • **kwargs (Any) – Keyword arguments for algorithm.run().

Return type:

Any

Returns:

The algorithm result (e.g. (energy, wavefunction)).

Examples:

# "scheduler" is provided by an installed plugin
# Shared cache — both sides use the same backend
shared = FolderCache("/mnt/shared/cache", is_shared=True)
energy, wfn = run(scf, mol, 0, 1, "cc-pvdz",
          cache=shared, remote="scheduler")

# Local cache backed by a shared cache for remote execution
cache = TieredCache([FolderCache("./cache"), shared])
energy, wfn = run(scf, mol, 0, 1, "cc-pvdz",
          cache=cache, remote="scheduler")