Conventions and Reference

The physics and numerical conventions used across the library. Most subtle bugs are convention mismatches, not logic errors; when validating numerics, check against this page first. Each convention below states how to verify it in a few lines.

Qubit ordering: qubit 0 is least significant

In statevectors and SpinOperator.to_matrix(), qubit 0 is the least significant bit of the computational-basis index — the rightmost factor in a Kronecker product. Basis state |q_{n-1} ... q_1 q_0> has index sum q_k 2^k.

Building a dense reference for an operator on qubit j of m qubits:

ops = [I] * m
ops[j] = Z
dense = functools.reduce(np.kron, ops[::-1])   # note the reversal

Verify: np.asarray(cudaq.spin.z(0).to_matrix()) on 1 qubit is diag(1, -1); on 2 qubits spin.z(0) acts on index bit 0.

Pauli words

Pauli words are strings over IXYZ with position = qubit index (word[0] acts on qubit 0), so "ZI" means Z on qubit 0 — reversed relative to most papers’ left-to-right tensor-product notation. Always translate at the boundary. Extract canonical term dictionaries with term.get_pauli_word(width) / term.evaluate_coefficient(), passing the intended qubit count as width so identity padding is explicit.

Spin orbitals: interleaved

Spatial orbital p maps to spin orbitals 2p (up) and 2p + 1 (down). All fermionic modules (the fermion transforms, the chemistry-facing helpers, the double-factorized encoding) use this convention. fermion_basis_change instead takes a spin-orbital matrix directly, one mode per qubit; lift a spatial matrix V with np.kron(V, np.eye(2)).

Fermionic integral tensors

n spin orbitals; tensors are coefficient arrays for normal-ordered ladder products, with no implicit symmetry factors:

\[H \;=\; c \cdot I \;+\; \sum_{pq} h_{pq} \, a_p^\dagger a_q \;+\; \sum_{pqrs} V_{pqrs} \, a_p^\dagger a_q^\dagger a_r a_s\]

The constant c is the scalar_offset argument. Any 1/2 factors from a chemist-notation source must already be folded into V. From a chemist (pq|rs) spatial tensor, the standard spin-orbital expansion is: reorder with eri.transpose(0, 2, 3, 1) (chemist -> coefficients of adag adag a a), scale by 1/2, and distribute over the four spin patterns (2p, 2q, 2r, 2s), (2p+1, 2q+1, 2r+1, 2s+1), (2p, 2q+1, 2r+1, 2s), (2p+1, 2q, 2r, 2s+1) — see tests/python/test_jordan_wigner.py for the reference implementation.

Note that many inequivalent tensor layouts encode the same physical operator (indices can be traded against fermionic antisymmetry). The transforms compile tensors exactly as given, so any valid layout works — but when comparing against external data (OpenFermion, literature tables), normalize the layout first or compare spectra rather than tensors.

Jordan-Wigner ladder operators

\[a_j^\dagger = \tfrac{1}{2} \, Z_0 \cdots Z_{j-1} \, (X_j - i Y_j), \qquad a_j = \tfrac{1}{2} \, Z_0 \cdots Z_{j-1} \, (X_j + i Y_j)\]

Dense reference (with the qubit-0-least-significant kron ordering): annihilator a_j = Z^{⊗j} ⊗ [[0, 1], [0, 0]] ⊗ I^{⊗(m-j-1)}, Kronecker-multiplied right-to-left.

Block encodings

For any BlockEncoding (e.g. PauliLCU, or the worked double-factorized example encoding):

  • The encoded block is <0|_anc U_A |0>_anc = H / alpha, with alpha the 1-norm of the encoded coefficients.

  • encode_kernel() circuits allocate the system register first (from the input cudaq.State), ancillas after — so the good subspace is the first 2**num_system amplitudes of the output state.

  • num_ancilla >= 1 always (single-term encodings get one idle ancilla).

  • Controlled variants take a combined [control, ancilla...] register with the external control at qubit 0, and reduce to the identity at control |0>.

Verify (the standard encode-block test):

out = np.array(cudaq.get_state(enc.encode_kernel(), state_from(ket)))
np.testing.assert_allclose(out[:2**enc.num_system],
                           (H_dense @ ket) / enc.alpha, atol=1e-12)

Sparse-access encodings

encode_sparse and qrom_oracles take a dense array, a scipy.sparse matrix (anything with tocoo()), or (rows, cols, vals) triples with integer-typed rows/cols and dim=; duplicate triples sum, zero entries are dropped, and a non-power-of-two dimension is zero-padded to the 2^num_system register. Symmetry is judged with a matrix-relative tolerance 1e-12 * max|H| and a missing mirror counts as an asymmetry. A Hermitian dilation [[0, A], [A^T, 0]] adds one system qubit as the most significant bit: A occupies the upper-right block, so basis states with the halves bit 0 index rows of A and states with the halves bit 1 index columns. report["max_row_nnz"] is the largest number of nonzeros in a row and report["slots"] the structure slots of the matching assignment (which may need more slots than max_row_nnz).

Qubitization walk

  • One walk step W = R U_A (encoding, then reflection R = I - 2|0><0|) block-encodes -H/alpha; its eigenphases are pi -/+ arccos(lambda/alpha). Much of the literature (e.g. Low-Chuang) uses the opposite reflection sign or the other operator order and quotes +H/alpha with eigenphases +/- arccos(lambda/alpha) — translate before comparing. Consumers of this library rely on the -H/alpha form.

  • walk_kernel(power) / Walk powers apply Chebyshev polynomials: the good-subspace block after p steps is T_p(-H/alpha).

  • Walk.moment(ket, k) returns <T_k(H/alpha)> (the sign convention is handled internally; no caller-side negation).

QSVT

Projector-phase convention; the exact 2x2 signal model of the circuit built by QSVT.kernel is implemented as reference_response in tests/python/test_qsvt.py — treat that function as the executable specification. A forward step is reflect_about_zero then the block encoding; qsp-convention sequences run doubled projector phases and differ from the model by exp(i * sum(phases)) (recover_real_time_evolution accounts for it). One more literature trap: QSPPACK’s native W_x rotation has imaginary off-diagonals, while the circuit’s response step is real — the bridge lives in the phase-generation options, and reference_response is the executable arbiter whenever they seem to disagree.

Reflection gate vs reflection observable

Same word, opposite sign — a standard source of off-by-a-sign bugs:

  • the gate common_kernels.reflect_about_zero is I - 2|0..0><0..0| (the all-zero state acquires -1);

  • the observable qubitization.reflection_observable is 2|0..0><0..0| - I (expectation +1 on the all-zero state).

Simulation targets and tolerances

The default CUDA-Q target is fp32: statevector results carry ~1e-7 error. All library tests pin qpp-cpu (fp64, via conftest.py) and assert at 1e-10..1e-12. When a probe shows ~1e-7 residuals, suspect the target precision before suspecting the code.

BLAS threading and C-DF reproducibility

Compressed double factorization runs an iterative optimization whose objective is evaluated through multithreaded BLAS. Thread scheduling changes floating-point reduction order, and over a few thousand optimizer steps that noise compounds into different local minima: two runs of identical code on identical input can return visibly different factorizations (reconstruction errors differing in the second digit). This is expected behavior of non-convex optimization on non-deterministic arithmetic, not a bug.

Before comparing C-DF outputs across code versions — bisecting a regression, validating a refactor, A/B-testing a change — pin the BLAS thread count:

OMP_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1 MKL_NUM_THREADS=1 \
    python your_comparison.py

Under pinned threads, runs of the same code are bit-for-bit reproducible, and any remaining difference is attributable to the code change. Unpinned comparisons of C-DF results are noise.

Hermiticity

eigvalsh, .real, and spectrum-sorting shortcuts are valid only for Hermitian operators. Generic coefficient tensors produce non-Hermitian operators; use np.linalg.eigvals and compare sorted complex spectra, or hermitize the input deliberately and say so.