[wsttiger]

Summary

Adds SparseOracleEncoding, the sparse-access block encoding of real sparse symmetric
matrices, three ways to feed it (banded_oracles, qrom_oracles, a hand-written
OracleKernels bundle), and encode_sparse(), the data-level constructor with validation,
optional Hermitian dilation and a cost report.

The implementation uses cudaq_algorithms.primitives and satisfies the BlockEncoding
protocol, so Walk and QSVT consume it unchanged. The public API is available from both
cudaq_algorithms.sparse and the package root.

The encoding

Builds U_A = T† S T from location and value oracles supplied through OracleKernels
(Camps, Lin, Van Beeumen & Yang, arXiv:2203.10236). Its normalization is
alpha = d_padded * h, with d_padded the padded number of structure slots and h a bound
on the largest matrix-element magnitude.

U_A is self-adjoint and involutory on every state whose work scratch enters |0>, the
domain the oracle contract guarantees and every consumer supplies; flat, work-free oracles
(banded_oracles) make the involution a global matrix identity, table oracles built on
unary-iteration walks (qrom_oracles) do not. Controlled application controls only the
middle factor, so the supplied oracles never need controlled versions. Negative off-diagonal
entries are supported; negative diagonal entries need a diagonal shift or the Hermitian
dilation.

The oracle contract. Every nonzero entry belongs to exactly one slot; a mapping that only
completes a slot's permutation loads zero, even where the matrix entry is nonzero and owned
by another slot; reverse slots carry mirrored entries consistently. qrom_oracles builds
bundles that satisfy this by construction, and a hand-written four-by-four oracle pins the
rule in the tests.

Inputs

• banded_oracles: arithmetic location and value oracles for matrices given by
  constant-valued bands, with boundary comparators preventing wraparound. Offsets of any
  magnitude are applied exactly: the Fourier-basis adder and comparator take each constant
  reduced per bit as an integer (K mod 2^(t+1)), the form primitives.phase_add_constant
  uses. Band symmetry is judged relative to the band scale.
• qrom_oracles: table-based oracles from the entries; a matching-based slot assignment
  makes each location map its own inverse, so the same kernel serves as its adjoint.
• from_general_oracles: the Hermitian dilation [[0, A], [A.T, 0]] of a real square
  A on one extra system qubit, from flat oracles of A.
• OracleKernels records the system width it was built for; the encoding rejects a
  mismatched width.

Data-driven inputs accept dense arrays, SciPy sparse matrices, or integer-indexed
(rows, cols, vals) triples; entries must be real and finite in both parts.

encode_sparse(matrix, value_bits=, dim=, dilate=, max_entries=) validates the data, prices
alpha and the register budget classically, builds the encoding over qrom_oracles, and
attaches encoding.report (alpha, qubits, nnz, max_row_nnz, slots, dim,
dilated, value_bits). A non-symmetric input or a negative diagonal raises, naming the
way out; dilate=True encodes the Hermitian dilation at the data level, where every entry
sits off the diagonal. max_entries bounds the QROM table; alpha must be finite.

Resource accounting

num_ancilla includes all ancillas, scratch included; num_block_ancilla / num_scratch
expose the breakdown. The encoding provides no select_observable, so Walk.moment serves
even orders only, and the shared reflection_observable raises above 20 ancillas rather than
expanding into 2^num_ancilla Pauli terms; Chebyshev data at these widths comes from
walk_kernel powers.

state_from(ket, num_qubits=None) gains an input-width check: with num_qubits given, a ket
of any other length raises instead of silently widening the system register (oversized) or
failing inside the simulator (undersized).

Validation

Three test files, run through CUDA-Q on 0.15.1 and 0.16. Circuit blocks are compared with the
exactly realized (quantized) matrices at 1e-10 and those with the intended matrices within the
derived quantization bound. Covered: Laplacian and permutation blocks; the involution on dirty
block ancillas with clean scratch (qrom_oracles) and on a fully dirty register
(banded_oracles); walk powers against T_k(-H/alpha); forward/adjoint round trips;
controlled application and controlled walks at |0>, |1> and a control in superposition;
QSVT against the signal model; protocol conformance; the dilation with padded slots and
signed non-symmetric input under the consumers; QROM-backed oracles at every shape (1×1, 2×2,
diagonal-only, non-power-of-two) with padded rows and columns zero; the location and value
oracles on basis states (locations, inverses, angle / sign / upper loads, fillers and padded
slots, clipped boundaries, clean work); two nontrivial reverse-slot pairs and the one-qubit
slot register; band offsets near the register limit and overlapping modular shifts; the
per-bit reduction checked analytically at 2^30 + 1 and 2^53 + 1 with the 54-qubit bundle
built; the hand-written-oracle contract with the double-counting counterexample; scale-relative
band symmetry at 1e-13, 1 and 1e6; encode_sparse reports, dilation and guards (fractional
offsets, non-finite entries, infinite alpha, table budget, input width).

Docs

API reference entries for the family, a "Sparse-access encodings" section in the
block-encodings guide, a conventions entry, and a README line.

Follow-ups

• Even moments from the all-zero-ancilla probability instead of a Pauli expansion, which
  would remove the 20-ancilla guard for every wide encoding.
• Natively controlled qrom_oracles bundles for from_general_oracles on top of the
  controlled QROM lookup (Add an externally controlled QROM lookup #70); automatic QROM-variant selection; complex matrices.

References

Camps, Lin, Van Beeumen & Yang, Explicit quantum circuits for block encodings of certain
sparse matrices (arXiv:2203.10236); the sparse-access
input model of Berry, Childs & Kothari (arXiv:1501.01715);
Low & Chuang (arXiv:1610.06546); Gilyén, Su, Low & Wiebe
(arXiv:1806.01838).

[smcardleQ]

SparseOracleEncoding looks great, and is architected in a natural way - see minor comments below.
I think we should remove SparseLCUEncoding. It is not clear to me that this is an efficient approach in general, and I am not aware of an algorithm in the literature that uses this method.

Requested changes

1. Fix scale-dependent symmetry validation in banded_oracles

The absolute 1e-12 tolerance accepts substantially asymmetric matrices when their entries are small.

For example, this currently passes validation:

oracles = banded_oracles(
    [-1, 1],
    [1e-13, 0.0],
    num_system=1,
    value_bits=6,
)
encoding = SparseOracleEncoding(oracles, num_system=1)

The requested matrix divided by alpha contains an off-diagonal entry of 0.5, but the encoded block is zero.

• Replace the absolute symmetry tolerance with a scale-relative check, consistent with the QROM input validation.
• Test asymmetric bands at several scales, including 1e-13, 1.0, and 1e6.
• Include missing-value and opposite-sign cases.
• Verify that equal tiny bands remain accepted and produce the expected quantized block.

Source: [symmetry validation](

cudaq-algorithms/python/cudaq_algorithms/sparse/_banded.py

Line 131 in cd92d44

if abs(v - by_offset[-o]) > 1e-12:

).

2. Preserve integer precision in the banded Fourier arithmetic

The current rotations convert the entire offset to a floating-point angle before reducing it modulo (2\pi). This loses precision for large valid offsets. For num_system=54 and offset=2**53 + 1, analytical evaluation gives only approximately 4.4% probability on the correct location-oracle output.

• Reduce each integer offset modulo 2**(t + 1) before converting it into the rotation angle.
• Apply this consistently to location, inverse-location, and boundary-comparison arithmetic.
• Test positive and negative offsets, including offsets near the register limit.
• Add analytical large-width tests, including 2**30 + 1 and 2**53 + 1, without requiring a large statevector simulation.

The existing arithmetic primitive already implements the appropriate reduction.

Sources: [banded arithmetic](

cudaq-algorithms/python/cudaq_algorithms/sparse/_banded.py

Line 215 in cd92d44

r1.ctrl(6.283185307179586 * offset / (1 << (t + 1)), slot,

), [existing integer reduction](

cudaq-algorithms/python/cudaq_algorithms/primitives/_arithmetic.py

Line 388 in cd92d44

# Only ``K mod 2^(t+1)`` affects reg[t]'s phase. Reduce it as an integer

).

3. Correct the custom-oracle contract for filler mappings

The documented instruction to load H[x, cinv(s, x)] unconditionally can double-count matrix entries. Permutation-completion mappings must load zero even when the corresponding matrix entry is nonzero.

For example, consider a 4×4 matrix with H[0,0] = H[1,2] = H[2,1] = 0.5. A matching slot swaps indices 1 and 2 while fixing 0; a separate slot handles the diagonal. Following the current formula loads H[0,0] in both slots.

• Explicitly document that every nonzero entry must be assigned to one slot, with consistent reverse-slot pairing.
• Specify that filler mappings load zero rather than looking up the corresponding matrix entry.
• Add a handwritten-oracle regression test using this example and verify the complete encoded block.
• Include a banded example where different modular location permutations overlap but their valid-value supports differ.

Sources: [oracle contract](

cudaq-algorithms/python/cudaq_algorithms/sparse/_sparse_oracle.py

Line 96 in cd92d44

``o_val`` XOR-loads, for slot ``s`` and register content ``x`` (the *row*

), [QROM filler handling](

cudaq-algorithms/python/cudaq_algorithms/sparse/_from_data.py

Line 160 in cd92d44

delta = [[0] * size for _ in range(num_loc)]

).

4. Tighten input validation

• Reject fractional band offsets before integer conversion. Currently, banded_oracles([0.9], [1], 2, 4) silently selects the diagonal.
• Check finiteness of both real and imaginary components before applying the real-valued tolerance. complex(1, float("nan")) is currently accepted as 1.0.
• Reject nonfinite normalization after computing d_padded * h. Finite input such as 1e308 * np.eye(2) currently produces alpha == inf.
• Add regression tests for each case.

Sources: [offset conversion](

cudaq-algorithms/python/cudaq_algorithms/sparse/_banded.py

Line 93 in cd92d44

offsets = [int(o) for o in offsets]

), [entry validation](

cudaq-algorithms/python/cudaq_algorithms/sparse/_sparse_lcu.py

Line 146 in cd92d44

def _real_entry(value, i: int, j: int) -> float:

), [normalization](

cudaq-algorithms/python/cudaq_algorithms/sparse/_sparse_oracle.py

Line 528 in cd92d44

return self._d_padded * self._h

).

Additional circuit tests

These should execute through CUDA-Q, rather than checking construction metadata alone.

• QROM dimensions and padding: reconstruct complete blocks for 1×1, 2×2, positive diagonal-only, and non-power-of-two matrices. Verify that padded rows and columns are zero.
• Direct oracle behavior: test location mappings, inverses, value/sign/upper-bit XOR loading, padded slots, clipped boundaries, and restoration of clean work qubits.
• QROM consumers: test controlled application, repeated walk powers, and QSVT against independent dense references.
• Reverse-slot branches: cover multiple nontrivial reverse-slot pairs and the controlled flip when the slot register has one qubit.
• Dilation: test padded slots, signed nonsymmetric input, controlled application, and walk/QSVT integration, including the factory’s forced-oracle dilation path.
• Control coherence: compare the complete controlled output with its reference, including a control prepared in superposition.

The state-taking convenience kernels also lack system-width validation. Add coverage for oversized and undersized input states and define their rejection behavior. This is a shared issue with existing Walk/QSVT interfaces, rather than a defect unique to this PR.

Verification limitation

The review used independent source-derived gate simulations and analytical checks. CUDA-Q was unavailable locally, so the repository’s CUDA-Q tests were not rerun. The added regression tests should confirm both the mathematical behavior and CUDA-Q compilation/runtime behavior.

[wsttiger]

Thanks for the thorough pass, and for the reproducers: all four ran here exactly as you described, on CUDA-Q 0.15.1 and 0.16.

SparseLCUEncoding is gone (commit f3cef96): the module, its tests and the two-path pricing. encode_sparse(matrix, value_bits=, dim=, dilate=, max_entries=) is now the data-level constructor for SparseOracleEncoding over qrom_oracles; negative diagonals and non-symmetric input raise with the way out (shift the diagonal, or dilate=True, under which every entry sits off the diagonal), and report carries alpha, qubits, nnz, max_row_nnz, slots, dim, dilated, value_bits.

1. Symmetry tolerance. Band symmetry is now judged relative to the band scale (1e-12 * max |value|), the same rule the matrix-data path already used. Tests at 1e-13, 1 and 1e6 reject a value against zero, two magnitudes and opposite signs, and check that equal tiny bands encode the expected quantized block.

2. Integer precision. The adder and comparator rotations take each constant reduced per bit as an integer, K mod 2^(t+1), the form primitives.phase_add_constant uses, in o_loc, o_loc_adj and the boundary comparator of o_val. Tests: the clipped band at offsets near the register limit (±7 on 3 qubits, −5, 3 on 2) through the circuit; bands whose modular shifts coincide (+1 ≡ −3 mod 4) but whose supports differ; and the analytic check you asked for, 2^30 + 1 and 2^53 + 1 (both signs) against exact rational phases, with the unreduced float shown to be off by π on bit 0 for 2^53 + 1, plus the 54-qubit bundle building without a statevector. (Your 4.4 % figure modelled the error differently; with the kernel's expression the low bit lands a full π off, so the location is simply wrong.)

3. Contract. The module docstring now states that every nonzero entry belongs to exactly one slot, that a mapping which merely completes a slot's permutation loads zero even where the matrix entry is nonzero and owned by another slot, and that the assignment must be consistent across reverse slots. qrom_oracles already did this (it writes a value only for rows in a slot's matching); the hand-written-oracle test on your 4×4 example checks the full block, and the double-counting reading is kept as the counterexample (the diagonal entry comes out doubled, nothing else moves).

4. Validation. Offsets must be integers (0.9 is rejected), an entry must be finite in both parts before the real tolerance applies (complex(1, nan) is rejected), and alpha = d_padded * h must be finite (1e308 * I is rejected in the encoding and before any kernel is minted in encode_sparse). Each has a regression test.

Circuit tests. A new file, test_sparse_circuits.py, runs the rest of your list through CUDA-Q: QROM-backed oracles at every shape (1×1, 2×2, diagonal-only, non-power-of-two 3×3) with padded rows and columns zero; the location and value oracles on basis states (locations and inverses, angle / sign / upper loads for assigned entries and zero for fillers and padded slots, clipped band boundaries, work qubits clean); controlled application, walk powers and QSVT of a QROM-backed encoding against dense references; two nontrivial reverse-slot pairs and the one-qubit slot register pair; the Hermitian dilation with padded slots and signed non-symmetric input under controlled application, the walk and QSVT (the factory's data-level dilation is pinned in the factory file); and a control in superposition against the full reference state. Register sizes stay at two system qubits for QROM-backed cases, since their work register adds 2n + d qubits and a 3-qubit case costs minutes per statevector; the file runs in about six minutes per CUDA-Q version.

Input width. The kernel boundary cannot check it (a kernel allocates whatever cudaq.qvector(state) implies, so an oversized ket silently widened the system and an undersized one failed inside the simulator), so state_from(ket, num_qubits=None) now takes the register width and raises on any other length; the state-taking kernels and the guide say to pass num_qubits=encoding.num_system. That is the shared Walk / QSVT fix as well, since every state-taking path builds its state through the same helper.

All of it runs through CUDA-Q on both supported versions; the branch is also merged with current main.