Backends

The divi.backends module provides interfaces for running quantum circuits on different backends, from local simulators to cloud-based quantum hardware.

All backends implement the CircuitRunner interface, providing a consistent API for circuit execution. This abstraction allows switching between different execution environments without changing quantum program code.

All submit_circuits() methods return an ExecutionResult object, which provides a unified interface for handling both synchronous and asynchronous backend responses.

Functions

convert_counts_to_probs(counts, shots)

Convert raw counts to probability distributions.

create_backend_from_properties(properties[, ...])

Create a populated GenericBackendV2 from a BackendProperties dictionary.

reverse_dict_endianness(probs_dict)

Reverse endianness of all bitstrings in a dictionary of probability distributions.

Classes

AsyncJobBackend(*args, **kwargs)

Backend that runs circuits as an asynchronous remote job.

CircuitRunner(shots[, track_depth])

A generic interface for anything that can "run" quantum circuits.

ExecutionConfig([bond_dimension, ...])

Execution configuration for a Qoro Service job.

ExecutionResult([results, job_id])

Result container for circuit execution.

JobConfig([shots, simulator_cluster, ...])

Configuration for a Qoro Service job.

JobStatus()

Status of a job on the Qoro Service.

JobType()

Type of job to execute on the Qoro Service.

MaestroConfig([simulator_type, ...])

Configuration object for MaestroSimulator.

MaestroSimulator([shots, config, track_depth])

A CircuitRunner backend powered by qoro-maestro, Qoro's C++ quantum simulator.

QPU(nickname, q_bits, status, system_kind)

Represents a single Quantum Processing Unit (QPU).

QPUSystem(name[, qpus, access_level, ...])

Represents a collection of QPUs that form a quantum computing system.

QiskitSimulator([n_processes, shots, ...])

A parallel wrapper around Qiskit's AerSimulator using Qiskit's built-in parallelism.

QoroService([auth_token, job_config, ...])

A client for interacting with the Qoro Quantum Service API.

SimulationMethod()

Simulation method for execution configuration.

Simulator()

Simulator backend type for execution configuration.

SimulatorCluster(name[, access_level, ...])

Represents a simulator cluster for cloud-based quantum simulation.

SupportsCircuitTemplates(*args, **kwargs)

Capability protocol for backends that resolve parametric QASM templates server-side.

Characterization

The divi.backends.characterization module provides QUBO/HUBO characterization and validation helpers that submit through QoroService.

QUBO/HUBO characterization public API.

Functions

characterize_and_validate(problem, ...[, ...])

One-call QUBO/HUBO characterization with rich notebook display.

get_characterization_result(job_id, *, service)

Re-fetch a previous characterization result by job ID.

Classes

CharacterizationResult(job_id, status[, ...])

Result container for QUBO/HUBO characterization.
pydantic model CharacterizationOptions[source]

Configuration for characterize_and_validate().

All fields are optional; default-construct for a basic run with no sub-analyses. Field combinations are validated at construction time, so misconfiguration surfaces before any API call.

Examples

>>> CharacterizationOptions(parameter_sweep=True, structural_sensitivity=True)
>>> CharacterizationOptions(gamma=1.2, beta=0.7)

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Fields:
field structural_sensitivity: Annotated[bool, Strict(strict=True)] = False

Request per-qubit structural sensitivity analysis.

Constraints:

  • strict = True

field parameter_sweep: Annotated[bool, Strict(strict=True)] = False

Request a γ/β parameter sweep.

Mutually exclusive with fixed gamma / beta.

Constraints:

  • strict = True

field penalty_tuning: Annotated[bool, Strict(strict=True)] = False

Request penalty-lambda tuning.

Requires BinaryOptimizationProblem(..., penalty=...) in the characterize_and_validate() call.

Constraints:

  • strict = True

field gamma: float | None = None

Fixed γ value. Mutually exclusive with parameter_sweep.

field beta: float | None = None

Fixed β value. Mutually exclusive with parameter_sweep.

field constraints: list | None = None

Constraint descriptors, each a dict {"type": ..., "bound": ...}.

Supported type values:

  • "max_cardinality" / "min_cardinality" / "eq_cardinality" — at most / at least / exactly bound variables set to 1.

  • "inequality" — weighted sum Σ wᵢ·xᵢ ≤ bound; requires a "weights" dict {qubit_index: weight}.

  • "equality" — weighted sum Σ wᵢ·xᵢ == bound; requires "weights".

Optional keys: "qubits" — the variable indices the constraint applies to (defaults to all; used by the cardinality types). Indices must be in [0, n_qubits) or the call is rejected. Example:

constraints=[
    {"type": "max_cardinality", "bound": 3},
    {"type": "inequality", "bound": 10, "weights": {0: 4, 1: 5, 2: 7}},
]
field ansatz: _Ansatz | None = None

Ansatz configuration dict (e.g. {"mixer": "x", "layers": 1}).

Supported mixer values are "x", "xy", and "I" (identity/no mixer, useful as a diagnostic baseline).

Only circuit-shape controls belong here. Search-space controls such as auto_warmstart, max_variable_qubits, base_bitstring, and variable_qubits belong in subspace.

field subspace: _Subspace | None = None

Subspace-search configuration dict.

Supported keys include auto_warmstart, solver, max_variable_qubits, base_bitstring, and variable_qubits. These controls choose or bound the simulated/search subspace; they are not properties of the QAOA circuit ansatz itself.

field n_qubits: Annotated[int, Strict(strict=True)] | None = None

Explicit qubit count for the problem.

Only needed to pin the dimension when a QUBO’s highest-indexed variable has no terms (so it can’t be inferred from the QUBO keys) — e.g. a problem on 5 variables where variable 4 is unconstrained. When None, the qubit count is inferred from the QUBO. Must be a positive integer.

Constraints:

  • gt = 0