How Divi Works
The building blocks
flowchart LR
P["Problem<br/>(graph, QUBO, molecule, Hamiltonian)"] --> Q["QuantumProgram<br/>(VQE, QAOA, PCE, QNN, ...)"]
Q --> C["Circuit pipeline<br/>expand → execute → reduce"]
C --> B["Backend<br/>(Maestro, Aer, QoroService)"]
B --> C
C --> O["Optimiser"]
O --> Q
Problems describe what to solve and produce a cost Hamiltonian. Examples are a graph problem such as MaxCut, a binary optimisation problem with optional constraints, a molecule, or an arbitrary Hamiltonian.
Programs (QuantumProgram, and VariationalQuantumAlgorithm for the variational ones) own the circuit, its parameters, and the optimisation loop. A new variational algorithm mainly needs a cost circuit and a parameter count. Execution, batching, checkpointing, and backend handling come from the base class.
The circuit pipeline turns one parameterised circuit into everything that actually has to run. It expands the circuit into measurement groups, parameter sets, and error-mitigation variants such as zero-noise-extrapolation folds and Pauli twirls. It then lowers the result to OpenQASM, submits everything as one batch, and reduces the raw results back to a single loss value. If the backend can compute expectation values itself, as Qoro’s cloud simulators do, measurement grouping is skipped and the observables are sent directly. If the backend can bind parameters on the server, a single template is sent instead of thousands of bound circuits.
Optimisers propose the next parameters. The options include SciPy methods, evolutionary strategies, Monte Carlo and grid search, SPSA, and quantum natural-gradient variants. The loop repeats until convergence or the iteration limit.
Ensembles and batching
Many workloads are naturally many programs: the clusters of a partitioned graph, the bond lengths of a potential-energy scan, the time points of a trajectory. A program ensemble runs them together, round by round. It creates programs, runs them, updates its state, and decides whether another round is needed.
The ensemble’s batch coordinator collects the circuits that all programs need for their current step and submits them to the backend as one merged job. On Qoro’s cloud this turns hundreds of small requests into one large job that Composer can spread across the simulator fleet or pack onto a QPU.
Dry runs
Every program and ensemble supports dry_run(). It builds the circuits without executing them and reports how many circuits, shots, and backend jobs a run would need, and how wide and deep the circuits are. Use it to check the cost of a run before spending credits or QPU time.
📖 For the full API, see divi.readthedocs.io.