ibm.qdmi.offloader

Offload Qiskit workloads (sampling and estimation) using Slurm.

Functions

extract_counts(→ dict[str, int])

Extract joint counts from the native sampler's single submitted circuit.

sample(→ dict[str, int])

Sample from a quantum circuit.

estimate(→ qiskit_algorithms.VQEResult)

Estimate the optimal parameters for a given ansatz circuit and operator.

Module Contents

extract_counts(primitive_result: PrimitiveResult[SamplerPubResult]) → dict[str, int]

Extract joint counts from the native sampler’s single submitted circuit.

Returns:

Joint bitstrings in Qiskit’s register order, mapped to shot counts.

Raises:

RuntimeError – If the result is empty or has no classical registers with counts.

sample(qc: QuantumCircuit, shots: int = 1024, *, local: bool = False, simulator: bool = False, timeout: float | None = None, backend_name: str | None = None, licenses: str | None = None, partition: str | None = None, nodes: int = _DEFAULT_NODES) → dict[str, int]

Sample from a quantum circuit.

When local=False (default), serializes the given circuit to QPY format and submits it to the Slurm workload manager using the srun command. After completion, the counts are parsed and returned as a dictionary.

When local=True, runs the circuit in this process on the selected backend.

Parameters:

  • qc – The quantum circuit to run.

  • shots – The number of shots to run. Default is 1024.

  • local – If True, run the job in this process on the selected backend. If False (default), offload to Slurm.

  • simulator – If True, run the job on the simulator instead of the quantum computer.

  • timeout – How long to wait for the Slurm job to complete, in seconds, before giving up. Only used when local=False.

  • backend_name – IBM backend selection, overriding IBM_QUANTUM_BACKEND. Applies to both local and Slurm execution. Ignored for simulation.

  • licenses – Optional Slurm license request, in name[:count] syntax. Only used when local=False.

  • partition – The Slurm partition to submit to, passed as –partition to srun. Defaults to the IBM_SLURM_PARTITION environment variable, and to quantum when that is unset. Only used when local=False.

  • nodes – The number of nodes to allocate, passed as –nodes to srun. The worker always runs as a single task (–ntasks=1), so this only sizes the allocation for sites whose partition demands more than one node. Default is 1. Only used when local=False.

Returns:

A dictionary of measurement counts.

Raises:

  • ImportError – If Qiskit or the QDMI backend plugins are not installed.

  • RuntimeError – Propagated from job submission or result decoding.

estimate(ansatz: QuantumCircuit, operator: SparsePauliOp, maxiter: int = 80, *, local: bool = False, simulator: bool = False, timeout: float | None = None, backend_name: str | None = None, licenses: str | None = None, partition: str | None = None, nodes: int = _DEFAULT_NODES) → VQEResult

Estimate the optimal parameters for a given ansatz circuit and operator.

When local=False (default), serializes the given ansatz and operator to QPY/pickle format and submits them to the Slurm workload manager using the srun command. After completion, the VQE result is parsed and returned.

When local=True, runs the VQE algorithm locally using either the MQT Core DDSIM simulator backend or the packaged IBM backend.

The returned result has the same semantics as calling VQE(…).compute_minimum_eigenvalue(…) directly against the regular (non-offloaded) estimator.

Parameters:

  • ansatz – The ansatz circuit to run.

  • operator – The operator to run.

  • maxiter – The maximum number of iterations for the optimization. Default is 80.

  • local – If True, run the job in this process on the selected backend. If False (default), offload to Slurm.

  • simulator – If True, run the job on the simulator instead of the quantum computer.

  • timeout – How long to wait for the Slurm job to complete, in seconds, before giving up. Only used when local=False.

  • backend_name – IBM backend selection, overriding IBM_QUANTUM_BACKEND. Applies to both local and Slurm execution. Ignored for simulation.

  • licenses – Optional Slurm license request, in name[:count] syntax. Only used when local=False.

  • partition – The Slurm partition to submit to, passed as –partition to srun. Defaults to the IBM_SLURM_PARTITION environment variable, and to quantum when that is unset. Only used when local=False.

  • nodes – The number of nodes to allocate, passed as –nodes to srun. The worker always runs as a single task (–ntasks=1), so this only sizes the allocation for sites whose partition demands more than one node. Default is 1. Only used when local=False.

Returns:

The VQE result, including the optimal parameters and eigenvalue.

Raises:

  • ImportError – If Qiskit or the QDMI backend plugins are not installed.

  • RuntimeError – If there is an error while submitting the job to Slurm or parsing the output.