qdk_chemistry.remote package

Remote execution and result caching for QDK/Chemistry algorithms.

Algorithms created through the registry accept remote and cache keyword arguments on run().

Usage:
>>> from qdk_chemistry.algorithms import create
>>> from qdk_chemistry.remote import create_remote
>>>
>>> scf = create("scf_solver")
>>> backend = create_remote("local")
>>> backend.connect()
>>> try:
...     energy, wfn = scf.run(structure, 0, 1, "cc-pvdz", remote=backend)
... finally:
...     backend.disconnect()
qdk_chemistry.remote.available_backends()

Return list of registered backend names.

Return type:

list[str]

qdk_chemistry.remote.create_remote(name, **config)

Create a configured remote backend instance.

Parameters:

  • name (str) – Backend name (e.g., “custom” or “local”)

  • **config – Backend-specific configuration options.

Return type:

RemoteBackend

Returns:

Configured RemoteBackend instance ready for use

Examples

>>> from qdk_chemistry.remote import create_remote
>>> from qdk_chemistry.algorithms import create
>>>
>>> remote = create_remote("local", timeout=7200, poll_interval=10.0)
>>> scf = create("scf_solver")
>>> energy, wfn = scf.run(structure, 0, 1, "cc-pvdz",
...                       cache="./cache", remote=remote)
qdk_chemistry.remote.get_backend(name, **config)

Create a backend instance by name.

Parameters:

  • name (str) – Backend name (e.g., “custom” or “local”)

  • **config – Backend-specific configuration.

Return type:

RemoteBackend

Returns:

Configured RemoteBackend instance

Raises:

ValueError – If no backend is registered with that name

qdk_chemistry.remote.resolve_cache(cache, **kwargs)

Normalise a user-supplied cache argument.

Accepts any of the following:

  • None returns None

  • A CacheBackend instance → returned as-is

  • A Path or path-like string → FolderCache(path=...)

  • A registered name string → looked up in the registry; extra kwargs are forwarded to the backend constructor.

Parameters:

  • cache (str | Path | CacheBackend | None) – Cache instance, registered backend name, filesystem path, or None.

  • **kwargs (Any) – Backend-specific configuration for a name or filesystem path.

Return type:

CacheBackend | None

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

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")
qdk_chemistry.remote.submit(algorithm, *args, remote, job_dir=None, **kwargs)

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.

Subpackages

Submodules