clifford_qc: A Python Toolkit for Quantum Simulation

AI summary

Overview

Research area: Quantum simulation software, specifically quantum algorithms for spin, lattice, and molecular models, with emphasis on subspace eigensolvers, measurement resource estimation, and reproducible benchmarking.

Technical level: Advanced. The paper assumes familiarity with Pauli operator algebra, variational quantum eigensolvers, quantum subspace expansion, and shot-noise statistics, though the software interfaces are described in practical terms.

Scope: This paper describes clifford_qc, a Python research toolkit built around a shared sparse Pauli-word algebra that connects Hamiltonians, density operators, gates, measurement observables, subspace solvers, and evidence-tagged benchmark records for small-system quantum simulation.

What This Paper Is About

Developing a quantum simulation method requires constructing Hamiltonians, choosing reference states, comparing eigensolvers, accounting for measurement cost, and validating results against classical calculations, and these steps are often implemented with different representations and separate bookkeeping. The paper presents clifford_qc as a common implementation layer so that these steps share one operator algebra, one measurement cache, and one record format. The goal is reproducible method development on small systems, not a claim of hardware advantage or a general simulation speedup.

Key Contributions

1. A common sparse Pauli algebra. The kernel represents operators as multivectors (MV) mapping packed Pauli-word codes to complex coefficients. Hamiltonians, density operators, gates, individual Kraus operators, and candidate-selection observables share multiplication, adjoints, and expectation-value evaluation. A separate public PauliSum container holds Hamiltonians and observables, with an exact to_mv/from_mv boundary using the same packed word codes. Jordan-Wigner, parity, and Bravyi-Kitaev encodings are available.

2. Integrated eigensolver comparison and exact diagnostics. The package implements VQE and ADAPT-VQE, the Adaptive Clifford-Algebra Subspace Eigensolver (A-CASE), fixed and adaptive operator-response subspaces, quantum-selected configuration interaction (QSCI), sample-based quantum diagonalization (SQD), selected-CI controls, and exact-sector comparisons of qubit-exchange and coupled-exchange pools plus a shared-unitary multi-root ADAPT. Diagnostics include second-moment blocks (SecondMomentBank), true Ritz residuals with resolution floors, folded-spectrum roots and refined Ritz vectors (FoldedSpectrum), and opt-in convergence reports.

3. Measurement and device-cost accounting. The toolkit supports qubit-wise and block-commuting grouping, Clifford readout circuits synthesized through a stabilizer tableau, anticommuting-clique compilation of a fixed functional, shared outcome caches, shot allocation, covariance, and confidence intervals. Device cards specify connectivity, gate times, a fidelity floor, and calibration status; settings that fall below the fidelity floor after routing are marked inadmissible.

4. Reproducibility infrastructure. The repository includes a prepare/solve/validate command-line pipeline, generated tables, provenance records, a versioned evidence contract validated at the opt-in producer stamp and by an automatic metadata gate on new or changed JSON records, and named benchmark gates. Process-isolated storage benchmarks compare object versus packed coefficients and retain-all versus streaming lifetime policies.

Main Findings

• Codebase scale: The package contains 110 modules and 29,000 physical lines, with 155 test modules and 37,607 test lines. The algebra kernel has 2,130 lines, the subspace solver layer 12,575 lines (43.4 percent of package lines), and the measurement layer 4,882 lines (16.8 percent).

• Memory-time trade in coefficient storage: Across four storage arms on five fixed molecular inputs, each run in a fresh process, packing and streaming reduced observed peak memory on the larger inputs at increased runtime. Excluding H4, whose observed peaks differ by at most 5 percent, packing alone lowered observed peak process memory by 49 to 63 percent, streaming object rows by 63 to 68 percent, and both together by 62 to 73 percent. The default object-retain arm was the fastest on every system. On BeH2 the peaks were 4.54 GiB (object retain), 2.32 GiB (packed retain), 1.66 GiB (object stream), and 1.71 GiB (packed stream), with wall times of 3.31, 5.04, 4.81, and 5.99 minutes respectively. Every arm completed under the campaign's declared memory ceiling, so neither option was needed for feasibility on these inputs.

• Measurement grouping has conditional value: Fully commuting readout certifies a fixed first-order Ritz functional with fewer shots, while anticommuting cliques help some fixed reference energies and not others. Entangling-gate time and connectivity can offset shot savings or make a protocol inadmissible under the illustrative device models.

• Shared measurements are real but conditional: In the two-site transverse-field Ising example with H = Z_p Z_q + X_p + X_q, the energy already requires Z_p Z_q, X_p, and X_q, while candidate gradient scores additionally require Z_p, X_p Z_q, and Y_p Y_q. Once estimated, the means of Z_p Z_q and Y_p Y_q contribute to two scores without separate samples. The shared cache exposes this overlap but does not make additional observables free, and a changed reference requires a new outcome cache.

• Odd-Y filtering is a selection rule, not a general restriction: For Hamiltonians and density operators real in the computational basis, the initial gradient of an even-Y Pauli rotation vanishes, so an exact gradient-based ADAPT run can omit even-Y candidates while following a real-state trajectory. Finite-shot rankings need not follow the same trajectory, and the molecular A-CASE path retains whole conserving excitation operators whose individual Pauli words need not preserve particle number or spin.

• Diagnostics are validated only in exact pairing: On the 5 frozen banks covered by validation records, the second-moment block, every Ritz residual, and every refined folded root agree with dense statevector oracles. No finite-shot estimator of the second-moment block K is shipped.

• Evidence coverage is incomplete but measured: Of 47 committed JSON records, 17 declare a single top-level evidence tier drawn from 5 distinct tier strings, 23 declare a per-quantity mapping, 5 nest the tier inside a sub-object, 2 declare an evidence role at the top level with tiers inside sub-objects, and 0 carry no record-level evidence field. A further 21 non-JSON series files are counted but not inspected for per-row declarations. Eight historical records take their declaration from a separately disclosed annotation bound to the record digest.

• Benchmark gating is split by cost: 63 producers write records and 65 gates read them. Of the 58 named in the continuous-integration workflow, 46 run on every pull request and 12 require manual dispatch; 7 gates exist in the repository but in no workflow. Reported gate classes include 1 kernel fixture audit, 2 exact trajectory replays, 1 observed resource equivalence gate, and 31 value-rebuilt gates.

• Negative and indeterminate results are reported: Further studies expose subspace bias, indeterminate encoding comparisons, failed approximate-restriction screens, and high residual-measurement costs under the tested uniform allocations.

• Explicit non-claims: The paper states that the results support reproducible method development and establish neither hardware performance nor a general simulation speedup. It provides no comparative benchmark against Qiskit, PennyLane, OpenFermion, Tequila, pytket, PyZX, or Stim.

Methodology in Plain English

The authors built a software library around one data structure: a sparse list of Pauli words with complex coefficients. Because Hamiltonians, quantum states, gates, and the observables used to score candidate operators can all be written in this form, the same multiplication and expectation-value routines serve every layer. Expectation values reduce to a trace pairing that only counts Pauli words present in both operators, so shared support is exploited directly.

They then layered interfaces on top of this kernel: a circuit program representation using Pauli rotors and named Clifford gates, statevector and stabilizer backends, model builders for spin chains and lattice models, subspace solvers, and measurement planners. A worked two-site Ising example shows how gradient scores for candidate operators are assembled from products of Hamiltonian terms, and which measurement results can be reused across scores.

For memory behavior, they ran the same adaptive solve under four storage configurations on five molecular fixtures (H4, BeH2, stretched BeH2, H2O, and stretched H2O), each in a fresh interpreter, and recorded peak resident memory and wall time. For measurement behavior, they compared grouping strategies and applied illustrative device models with connectivity, gate times, and fidelity floors. For reproducibility, they separated record generation from validation, attached evidence tiers to each reported quantity, and added automated gates that rebuild or check benchmark records. The molecular workflow is exposed as separate prepare, solve, and validate command invocations so that preparation, a large matrix-element bank, and a reference eigensolve need not coexist in memory.

Why This Matters

Impact on research: The toolkit makes the error budget of a subspace calculation attributable. Subspace bias, sampling uncertainty, device cost, and memory policy are recorded separately rather than collapsed into one number. Exact Ritz residuals and second-moment blocks guard against the common mistake of treating a small projected residual as proof of eigenstate convergence. The evidence contract and benchmark gates give other researchers a way to check which claims a stored number actually supports.

Real-world applications (prospective, not demonstrated on hardware):

• Molecular electronic-structure studies in minimal active spaces, using FCIDUMP integrals and fixtures such as H4, BeH2, and H2O.
• Spin-chain and Hubbard-type lattice model exploration with reusable model construction and exact sector execution.
• Resource estimation for measurement protocols on near-term devices, including whether a readout scheme is admissible under stated connectivity and fidelity assumptions.
• Teaching and prototyping quantum algorithm pipelines where exact classical checks are available.

Industry relevance: The package is explicitly positioned beside, not instead of, established frameworks, with optional adapters for Stim, OpenFermion, pytket, PennyLane, and PyZX. Its emphasis on evidence categories, provenance, and admissibility checks speaks to a practical industry need: distinguishing a benchmark number from a hardware claim. The measured memory reductions are relevant to running larger classical simulations on fixed hardware, while the reported runtime penalties show the trade explicitly.

Future Directions

• Finite-shot estimation of the second-moment block. The paper reports that no finite-shot estimator of K is shipped, leaving sampled residual diagnostics as an open implementation gap.
• Shot allocation beyond uniform allocation. The reported high residual-measurement costs under the tested uniform allocations point to adaptive or accuracy-targeted allocation as a next step; the device-cost module currently prices settings but does not allocate shots to an accuracy target.
• Resolution of indeterminate comparisons. The paper reports indeterminate encoding comparisons and failed approximate-restriction screens, which invite better-controlled studies of when a given encoding or restriction actually helps.
• Scaling and hardware validation. All results are small-system and classical; testing whether the memory-time trade and measurement savings persist on larger sectors or real devices is left open, and the device models are illustrative project scenarios rather than hardware calibrations.

Target Audience

Quantum algorithm researchers who need a consistent environment for comparing variational and subspace eigensolvers; quantum software developers interested in operator-algebra design, measurement caching, and evidence-tagged benchmarking; graduate students in quantum information or computational chemistry who want a readable worked example of gradient-based candidate selection and subspace diagnostics; and reproducibility or research-software engineers who need a concrete model for versioned evidence contracts and automated benchmark gates. Readers seeking hardware performance claims or head-to-head comparisons with mainstream frameworks will not find them here.

Authors’ abstract

clifford_qc is a Python research toolkit for constructing quantum models, comparing variational and subspace eigensolvers, and estimating measurement resources. A common sparse Pauli algebra connects Hamiltonians, density operators, gates, and candidate-selection observables; dedicated interfaces handle circuits, execution, and statistical estimates. A worked gradient example illustrates shared measurements, and a molecular workflow separates reusable preparation, solving, and reference validation. Matrix-element banks support virtual subspaces, exact Ritz residuals, and folded-spectrum roots. Process-isolated benchmarks show that packed coefficients and streaming reduce observed peak memory on the larger tested inputs at increased runtime. Measurement studies separate setting counts, shot requirements, and device cost: fully commuting readout certifies a fixed first-order Ritz functional with fewer shots, while anticommuting cliques help some fixed reference energies and not others. Entangling-gate time and connectivity can offset shot savings or make a protocol inadmissible under illustrative device models. Further studies expose subspace bias, indeterminate encoding comparisons, failed approximate-restriction screens, and high residual-measurement costs under the tested uniform allocations. Generated tables, provenance records, a versioned evidence contract, and manuscript checks connect claims to their inputs. These small-system results support reproducible method development and establish neither hardware performance nor a general simulation speedup.