v0.13.0

0.13.0 (2026-07-29)

v0.13 broadens the optimizer library with Quantum Natural Gradient, SPSA/QN-SPSA, and QUIVER, backed by a pluggable metric-estimator contract, and unifies measurement behind QuantumProgram.evaluate() and named CircuitPreprocessors. Aggregation becomes pluggable through first-class AggregationStrategy objects, including a new HierarchicalStrategy that preserves solution validity better than greedy beam pruning. QUBO characterization graduates into a public divi.backends.characterization package with configurable presets, a qaoa_initial_params() warm start, and job recovery that survives ambiguous submissions, while VQE and TimeEvolution gain PySCF and OpenFermion inputs via a new chem extra.

⚠️ Breaking Changes

If you are upgrading from v0.12.x, review the following before merging:

What changed	Migration
aggregate_results / get_top_solutions no longer accept beam_width or n_partition_candidates	Pass a strategy object instead: strategy=BeamSearchStrategy(beam_width=...) reproduces the previous default. Use strategy=HierarchicalStrategy(...) for the new aggregator. Affects ProgramEnsemble and PartitioningProgramEnsemble.
PCE no longer accepts a raw QUBO/HUBO matrix and raises TypeError	Wrap the matrix in a BinaryOptimizationProblem before constructing PCE, matching QAOA's constructor.

---

✨ Added

• qprog: add Quantum Natural Gradient (QNG) optimizer and metric estimators, including QNG+QDrift via deterministic per-evaluation sampling for wide-qubit workloads (f5a8634, d7c534c, 14d9369)
• qprog: add SPSA and QN-SPSA optimizers (d769665, a477bbf, e8b7a97)
• qprog: add QUIVER, an adaptive directional-gradient optimizer (2f68b8c, ade6347, a3f8bdb)
• qprog: unified measurement API — QuantumProgram.evaluate() is the single entry point for measuring a program under a named CircuitPreprocessor, consolidating observable grouping and adaptive shot allocation in MeasurementStage (485cfdd, 4e791f3)
• qprog: aggregation strategies are now first-class objects (AggregationStrategy/BeamSearchStrategy/HierarchicalStrategy); the new HierarchicalStrategy enumerates combinations within small groups and merges pairwise instead of greedily pruning after each partition, better preserving solution validity. Breaking: this replaces the beam_width/n_partition_candidates keyword arguments on aggregate_results/get_top_solutions — pass strategy=BeamSearchStrategy(beam_width=...) for the previous behavior (159c4a7, 927cfc6, ea657ec)
• qprog: accept PySCF and OpenFermion chemistry inputs — adds an optional chem extra; VQE(molecule=...) now accepts a PySCF Mole/restricted mean-field, and hamiltonian= on VQE/TimeEvolution/QAOA accepts an OpenFermion QubitOperator via to_spo (closed-shell/RHF only for now) (6868ea9)
• qprog: measurement groups now measure only observable-relevant qubits, shrinking sampling histograms while leaving expectation values unchanged (pass measure_all_qubits=True to opt out); also extends PCE past 64 qubits via a limb-based mask representation (106f218)
• backends: QUBO characterization result API + warm-start helper — splits the characterization client into a divi.backends.characterization package exposing CharacterizationResult (regime/certificate/AR/refuse_reason/regime_diagnostics), a pydantic CharacterizationOptions, and a qaoa_initial_params() warm-start helper (59d40e8)
• characterization: configurable presets and analysis options, plus hardened job recovery — job IDs now survive ambiguous submit/retrieve failures, existing jobs can be polled, and terminal statuses are handled consistently (b4dfdad)
• qprog: ProgramEnsemble.dry_run() previews a whole ensemble at once, with a new format_dry_run rendering the reports as a tree, one summary row each, or grouped by shape so a sweep collapses to its distinct configurations (165693f)
• qprog: community-based QUBO decomposition via CommunityDecomposer (6286455, b8d74a5)
• characterization: typed properties for the classical baseline and constraint diagnostics — classical_baseline, relaxation_bound, cost_gap_normalized, global_flip_symmetric, constraint_diagnostics, and the safe-penalty interval — surfaced in the console report (ae4c225)
• pipeline: dry-run previews now report shots and cadence alongside circuit counts, plus a fingerprint of the objective for telling two programs apart, via a documented dataclass report (replacing an under-documented NamedTuple) (d3dbd66)
• pipeline: routines now declare a cadence (recurring by default), so telling a routine re-evaluated across a working set from one that runs once no longer means hardcoding a routine name like "sample" (cb6dd6f)
• backends: QoroService.max_retries defaults to unlimited polling instead of capping at 5000 attempts, so long-running jobs are no longer dropped; passing an int still caps attempts, and progress displays render an unlimited cap as ∞ (f042368)
• backends: expose noise config fields and validate ExecutionConfig (#90) (5f10796)

🐛 Fixed

• circuits: give QuEPP's symbolic-angle fallbacks a warning category (292a267)
• circuits: QN-SPSA's build_overlap_meta keeps its backward parameters disjoint from the ansatz's (bc8f2fd)
• circuits: stop ZNE from folding the caller's DAG in place (76c0500)
• pipeline: correct what the stages report about themselves (e87bbc5)
• pipeline: default param_sets to a shape the binding stage accepts (055e8c7)
• pipeline: keep the analytic expval path when shot_distribution is set (de70c67)
• pipeline: reject circuit bodies that share a tag (365da61)
• pipeline: reverse counts endianness in expectation conversion (160b224)
• qprog: isolate optimizer RNG and purify pipeline-env building (c399229)
• qprog: unseeded QDrift stays cohort-consistent under QNG (875d4e1)
• qprog: make max_iterations a total for every optimizer (25d735b)
• qprog: reject unclaimed run() and ansatz keywords (cca7a44)
• qprog: require BinaryOptimizationProblem for PCE — breaking: PCE no longer accepts a raw QUBO/HUBO matrix and raises a clear TypeError instead, matching QAOA's constructor; wrap the matrix in a BinaryOptimizationProblem (cdb0bed)
• qprog: stop dry_run() from disturbing the run that follows (5a75a90)
• quepp: stop double-counting observable coefficients (8be41ad)
• resolve review findings across ZNE, QNG, sampling, and counts conversion — ZNE's k-fold pass no longer duplicates barriers/measures/resets and rejects invalid scale factors up front; QNG raises an actionable error on a singular damped metric and run() rejects checkpointing for optimizers that cannot save state; counts-endianness reversal now applies to any bitstring→count mapping (c670032)

🔄 Changed

• hamiltonians: compute the QDrift keep/sample split once per batch (2c59220)
• pipeline: carry measurement metadata on MetaCircuit (d1f4fae)
• pipeline: clarify cache identifier names (3471e25)
• pipeline: introduce StageOutput as the stage return type (94f14fe)
• qem: extract ZNE into its own zne.py module and derive QEMStage.consumes_dag_bodies from whether the protocol mitigates, instead of inline _NoMitigation checks (d5ed005)
• qprog: QN-SPSA caches its overlap circuit and rejects zero-iteration runs (c9bbc68)
• qprog: metric estimators share a single contract (7e64879)
• qprog: reworked how programs build and run their measurement pipelines, landing shared execution/accounting in QuantumProgram._execute, a reusable expectation pipeline for cost circuits, and an extracted SolutionSamplingMixin (3555bde, 0503927)
• qprog: a program now exposes a single derived n_params, replacing five hand-written n_layers * n_params_per_layer computations (742fc58)
• qprog: split optimizers into a package (one module per optimizer plus a shared _linalg helper) and harden best-result selection against non-finite losses across Scipy, Pymoo, MonteCarlo, and GridSearch (e9f14e8)

🔧 Internal

• backends: drop xfail from noise config e2e (fe24ddb)
• backends: skip the execution-config test on a PENDING race (52d5ef7)
• deps: upgrade qiskit to 2.5 and refresh dependencies (40c391a)
• enable uv package cache in setup-divi's astral-sh/setup-uv step and bump actions/checkout to v6 across workflows (f893bad, d1a75c7)
• refresh references to renamed ensemble classes — GraphPartitioningQAOA/QUBOPartitioningQAOA no longer exist; the partitioning workflow is PartitioningProgramEnsemble (654c4b5)
• update pre-commit hooks to latest and apply Python 3.13 standards (1a57ec3)

📝 Documentation

• describe the shot-distribution strategies without ranking them (c4a0182)
• fix the QEM guide's cost figures and reduce() contract (d97d4e0)