v0.12.0

0.12.0 (2026-06-05)

v0.12 migrates the Hamiltonian layer to Qiskit's SparsePauliOp: all QAOAProblem subclasses now return SparsePauliOp from cost_hamiltonian and mixer_hamiltonian, and the Ising-conversion and trotterization hot paths drop the O(N²) PennyLane operator-tree in favour of Qiskit's sparse representation. New capabilities include a QNN algorithm with feature-map encoders, Maestro noise models as first-class inputs, adaptive shot allocation across measurement groups, sample_solution() for post-training resampling without re-running optimization, and analytic dry-run fan-out counts across the full pipeline.

⚠️ Breaking Changes

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

What changed	Migration
QAOAProblem.cost_hamiltonian and .mixer_hamiltonian now return SparsePauliOp instead of pennylane.operation.Operator	Replace PennyLane-specific attribute access (.wires, .coeffs) with SparsePauliOp arithmetic. Use divi.hamiltonians.to_spo() for any operator you supply as input. Affects all subclasses: MaxCutProblem, BinaryOptimizationProblem, GraphPartitioningQAOA, routing problems.
parse_vrp_file renamed to parse_tsplib_file; VRPInstance renamed to RoutingInstance	Update all import and call sites in divi.qprog.problems.
StageInfo.fan_out: int replaced by StageInfo.factor: float	Replace .fan_out with .factor everywhere. Values > 1 are fan-outs, values < 1 are reductions.
pennylane-qiskit is no longer a transitive dependency	Add pennylane-qiskit explicitly to your project if you call its APIs directly.

---

✨ Added

• backends: expose Maestro noise models in divi; multi-observable QEM support (0caeaf6, 42775ab)
• backends: adaptive shot allocation across measurement groups via shot_distribution on MeasurementStage (f6d5a89)
• backends: parallel observable grouping in QEM (d70c44d)
• dry-run: surface shot budget, per-stage depth/width stats, and QEM variance signal in dry-run output (2724cd6)
• hamiltonians: to_spo now accepts PennyLane operators and {pauli_string: coeff} dicts in addition to SparsePauliOp pass-through (d2c5858)
• hamiltonians: new qubo_to_spo helper converts a QUBO matrix to SparsePauliOp with the loss constant folded in as an identity term (d2c5858)
• pipeline: analytic dry runs with exact fan-out counts via Stage.dry_expand() (05ef63f)
• qprog: QNN algorithm with feature-map encoders (AngleEmbedding, ZZFeatureMap) for supervised quantum machine learning (0af2213)
• qprog: sample_solution() runs only the final measurement step so trained parameters can be reused without re-running optimization; extended to ProgramEnsemble and replaces compute_solution() (c33468a, ad0beee)
• qprog: strict partition ensemble postprocessing via get_top_solutions(..., strict=True) (4e8fe6e)
• qprog: data-binding pipeline for CustomVQA and PennyLane circuit ingestion via qnode_to_meta/qscript_to_meta (fc8e371)
• qprog: max_concurrent_programs on BatchConfig caps ensemble concurrency and prevents batch-coordinator thread exhaustion (f05386e)
• qprog: create_tsp_qubo is now importable from divi.qprog.problems (425f963)
• routing: extended TSPLIB parser — supports EXPLICIT and GEO edge-weight types with conformant rounding (7dcfe78)
• routing: binary CE-QAOA encoding for TSP via encoding="binary" on TSPProblem (7dcfe78)

🐛 Fixed

• qprog: BatchConfig(max_batch_size=N) was silently ignored — executor pool now correctly caps at min(max_batch_size, len(programs)), preventing both undersized batches and thread exhaustion on large ensembles (79ebbb9)
• hamiltonians: wire-permutation bug that mis-decoded dict-input BQM solutions (9c33a03)
• qprog: harden ProgramEnsemble re-dispatch and coordinator concurrency (a3ecdba)
• qaoa: enforce cost/mixer/wire_labels qubit-count alignment at construction time (d996899)
• pipeline: restore imag-coeff warning accidentally dropped via the tuple-flatten path (99696c1)
• pipeline: surface warning when QuEPP's zero-path no-op would silently pass through noisy results (99696c1)
• pipeline: take the bound path under per-group shot allocation (1ff4275)
• backends: magnitude-based truncation for factored QUBO payloads (91061a5)
• guard shot_groups merge kwargs and custom shot-distribution truncation (905d3c8)
• noisy_execute should not strip measurements (7cb2cb3)
• set seed in noisy_estimate_montecarlo (5442fe2)
• stress-test hardening for ensembles, QAOA, QUBO, and reporting (19b0e76)
• ZNE: implement missing dry-run feature (1256650)

🔄 Changed

• hamiltonians: migrate Hamiltonian arithmetic to SparsePauliOp across trotterization, Ising-conversion, and QAOA cost-layer paths; adds thread-safe PL↔SPO cache with LRU cap (9c33a03)
• hamiltonians: qubo_to_ising rewrites Pauli-sum construction from O(N²) to O(N) (d050730)
• qprog: Qiskit-native internals for QAOA/VQE/TimeEvolution (99ba3a6)
• qprog: cancellation unified across single-program, pipeline, and ensemble run paths (76c7b4e, 415d7e4, 53c5c9f)
• qprog: introduce ObservableMeasuringMixin across observable-measuring programs (41b7b70)
• qprog: cache parametric MetaCircuit across TimeEvolutionTrajectory time points (fa786c1)
• qprog: standardize precision and hoist QuantumProgram properties (981657e)
• qprog: tighten QAOA ansatz, cache safety, and doc notes (4ae1056)
• qaoa: emit Qiskit gates directly in cost circuit construction (83f558e)
• QoroService: defer parameter binding via template submissions (8443228)
• maestro: consolidate noise knobs into MaestroConfig (3037c9e)
• backends: bandwidth-adaptive QUBO wire format for validation (b2e5b72)
• pipeline: measurement grouping reported as a ÷K reduction factor in dry-run output (115545c)
• pipeline: unify circuit-body QASM into one MetaCircuit field (b7e79e9)
• reporting: single Progress display, queue-only update lane, terminal-status enum (51ce865)
• ai: hybrid retrieval with cross-encoder rerank and LLM scope classifier (a5bfbf2)
• tutorials: consolidate, reorganize, and de-noise tutorial notebooks (cb3bc55, bf1e468)
• consolidate multi-observable handling, dedupe QuEPP/grouping paths (4558ceb)
• rename PennyLane import alias qml → qp across source, tutorials, and docs (fcf6c08)

🔧 Internal

• adopt pyrefly type checker; three-pass cleanup with tutorial-driven API hardening and type-native graph partitioning (c278a2b, a22504a, 000af2c)
• add style-check workflow and pyrefly pre-commit hook (8e14f84)
• factor CI workflow setup into composite actions (8a2fdf6)
• backends: add MaestroConfig unit tests (a86a27e)
• tests: reorganize test suite around per-package shared modules (d263828)
• tighten import boundaries (0b32295)
• reduce batch size to avoid OOM issues (394343e)

📝 Documentation

• add QUBO characterization page and audit fixes (02fc14f)
• readme: add Context7 callout for LLM coding agents (9c69374)
• ai: fix llama-cpp-python install troubleshooting (9657d84)