Qubitization and QSVT
Given a block encoding (see Block encodings), qubitization builds a
walk operator W whose eigenphases encode the spectrum of H / alpha,
and quantum singular value transformation (QSVT) applies a polynomial to
that spectrum by interleaving walk steps with signal-processing phases.
Both Walk and QSVT are generic over the encoding — they consume any
object satisfying the BlockEncoding protocol — and both have controlled
variants. QSVT-based Hamiltonian simulation is one of the two
time-evolution routes in the library; Trotter (product-formula simulation) is the other
(product-formula) route.
Everything below is pure-Python CUDA-Q kernels needing only cudaq and
numpy. Qubit-ordering and normalization conventions live in
Conventions and Reference. Import the object surface from the package root:
from cudaq_algorithms import Walk, QSVT, PhaseSequence
The qubitization walk
Walk wraps an encoding and emits the qubitization walk operator W and
its powers. The constructor holds the problem; the method calls hold the
choices:
walk = Walk(enc)
walk.kernel(power=3) # PREPARE + W^3 + UNPREPARE
walk.kernel(power=3, uncompute=False) # ... without UNPREPARE
walk.adjoint_kernel(power=2) # (W dagger)^2
walk.roundtrip_kernel(power=2) # W^2 (W dagger)^2 == identity
walk.controlled_kernel(power=2) # controlled walks
The flagged block of a single walk step is -H/alpha (the sign is folded
into the walk construction), so on an eigenstate with eigenvalue lambda
the good subspace realizes the Chebyshev response at lambda / alpha with
no caller-side negation. roundtrip_kernel composes a walk with its adjoint
and must collapse to the identity — the property tests pin this.
Chebyshev moments
Walk measures Chebyshev moments of the (normalized) Hamiltonian through
cudaq.observe, which is a hardware-legitimate measurement path:
walk.moment(psi, k) # <T_k(H/alpha)> via cudaq.observe
walk.moments(psi, 8) # even/odd observable convention
from cudaq_algorithms import reflection_observable, select_observable
reflection_observable(enc) # 2|0..0><0..0| - I (SpinOperator)
select_observable(enc) # sum_i sign_i |i><i| x P_i
There are two moment observables. The even moments use the reflection
observable 2|0..0><0..0| - I, which needs only the register geometry, so
Walk derives it without an encoding hook. The odd moments use the
encoding-specific select_observable, measured after PREPARE and p walk
steps (no UNPREPARE), whose expectation is <T_{2p+1}(H/alpha)>. This
presumes a walk step defined in the PREPARE frame (W = PREPARE R
PREPARE-dagger SELECT), as both PauliLCU and LCUBlockEncoding do. For
an LCU this is sum_i sign_i |i><i|_anc x P_i (select_observable(enc)
serves both PauliLCU backends; LCUBlockEncoding derives it when every
SELECT body is a Pauli word); encodings that cannot supply it
(for example DoubleFactorizedEncoding, or LCUBlockEncoding with a body
in the extended vocabulary) raise NotImplementedError on
select_observable, and only even moments are available there.
QSVT and phase sequences
A PhaseSequence is the list of signal-processing angles that define the
polynomial to apply; QSVT interleaves them with walk steps:
seq = PhaseSequence(phases) # projector convention
seq = PhaseSequence(phases, convention="qsp") # QSPPACK convention,
# converted automatically
seq = PhaseSequence(phases, walk_directions=["forward", "adjoint"])
transformer = QSVT(enc)
kernel = transformer.kernel(seq) # @cudaq.kernel(state)
controlled = transformer.controlled_kernel(seq) # controlled sequence
PhaseSequence accepts phases in either the projector convention (default)
or the QSPPACK "qsp" convention, which it converts automatically;
walk_directions lets a sequence mix forward and adjoint walk steps.
Sign convention: the walk block-encodes -H/alpha and the circuits fold
the sign in, so on an eigenstate with eigenvalue lambda the good-subspace
block implements p(lambda / alpha) — no caller-side negation. The 2x2
signal-model reference implementing this convention lives in
tests/python/test_qsvt.py (reference_response), where it serves as the
test oracle. Phase generation stays external (see below): the primitives
consume whatever phase list they are given.
Hamiltonian simulation
Real-time evolution exp(-iHt) is not a single polynomial (it is
complex), so QSVT realizes its real and imaginary parts separately — a
cosine and a sine polynomial in H/alpha — and they are recombined:
from cudaq_algorithms import recover_real_time_evolution
evolved = recover_real_time_evolution(cos_state, sin_state,
cos_phases, sin_phases)
Phase-angle generation is external to the library. The primitives
consume whatever PhaseSequence they are handed, so any source of angles
works — you can supply your own. QSPPACK
is one optional, example-only way to compute angles for a target function;
it is not a runtime dependency of cudaq_algorithms. The worked example
hamiltonian_simulation_qsvt.py on the Hamiltonian-simulation
examples page uses QSPPACK
(and scipy) to generate the cosine/sine phases, runs QSVT time evolution,
and compares against exact diagonalization, reaching ~1e-15 state error.
The getting-started series applies the same machinery to a different
function: 07_matrix_inversion_qsvt.py (Getting-started walkthrough)
inverts a linear system through a polynomial approximation of
\(1/x\) — the QSVT reading of HHL — changing nothing but the phase
sequence.
Quantum phase estimation
PhaseEstimation estimates eigenvalues of H from any BlockEncoding by
phase-estimating its qubitization walk: W has eigenvalues
e^{±iθ} with cos θ = -E/alpha on each eigenspace of H, so an
m-bit readout j decodes as E = -alpha cos(2π j / 2^m). No time
evolution and no phase-angle synthesis are needed — the controlled walk,
the inverse QFT and state preparation are already in the library.
from cudaq_algorithms import PauliLCU, PhaseEstimation, sim_utils
qpe = PhaseEstimation(PauliLCU(hamiltonian))
circuit = qpe.kernel(6, state_prep=prep) # measurement-free
measured = qpe.kernel(6, state_prep=prep, measure=True) # measures the phase register
counts = cudaq.sample(measured, shots_count=2000) # any target
ranked = qpe.energies_from_counts(counts, 6, top=3) # [(energy, probability), ...]
exact = sim_utils.qpe.energies(qpe, 6, state_prep=prep, top=3) # statevector, simulators
The class builds circuits and decodes readouts; running a circuit is your
executor on your target. measure=True measures the phase register
alone, so the sampled bitstrings are that register (qubit 0 first);
PhaseEstimation.energies_from_counts also accepts counts over every
qubit, as sampling the measurement-free circuit produces, and plain
mappings. The statevector shortcut, sim_utils.qpe.phase_probabilities
and sim_utils.qpe.energies, gives the exact marginal on a simulator.
The circuit is the textbook ladder — 2^m - 1 controlled walk steps and
an inverse QFT — so num_bits is the cost knob; the register layout is
system, then the m phase qubits (little-endian: phase qubit 0 is the
least significant readout bit), then the encoding’s ancillas. Each
eigenvalue appears at the mirror readouts j and 2^m - j, and
energies folds the pair into one entry, so a pure eigenstate reads as a
single dominant energy. The energy resolution is about
alpha π / 2^m; a general input spreads its mass over the spectrum in
proportion to its overlaps.
Two simulation notes for long ladders. The compiler re-materializes the
walk step’s captured tables on the host stack on every loop iteration
(about 1 kB per step for a PauliLCU), so from num_bits = 13 the
circuit outgrows the default 8 MiB thread stack and the process dies with
a segmentation fault; the sim_utils.qpe helpers run the simulation on a
worker thread with a large stack, and a circuit you sample on a simulator
needs the same
(sim_utils.run_on_large_stack(cudaq.sample, measured, shots_count=...)).
On the nvidia target, gate fusion’s host-side cost grows with the
circuit length; with fusion off (CUDAQ_FUSION_MAX_QUBITS=0) a 13-bit
H2 ladder runs in about half a minute on one GPU. The worked example
08_quantum_phase_estimation.py (Getting-started walkthrough)
puts a hand-written QPE shell around three oracles — exact time evolution,
a product formula and this walk — to compare their decoders; PhaseEstimation
packages the walk case.
The worked example also executes the packaged API on the same H2 Hamiltonian and Hartree-Fock preparation, alongside the three-oracle comparison. This is another implementation of the walk approach, not a fourth physical oracle. Core/nuclear energy is already encoded once.
It checks that the exact centered and textbook phase marginals agree bin by bin (the centered schedule’s extra \(W^{-M/2}\) is a phase on each walk eigencomponent, so the readout distribution is unchanged), then compares seeded 20,000-shot histograms to the exact unfolded marginals using an a priori total-variation bound. With M=2^m bins and failure budget delta, the bound is
At m=6, S=20,000 and delta=1e-6, this is about 0.0384. The sampling check uses unfolded distributions: folding mirror bins coarsens a distribution and can only lower total variation, so a folded check is weaker. Energy acceptance uses the cosine of the neighboring half-bin edges, clipped to the folded endpoints, rather than a uniform energy tolerance or fitted offset. QPE retains the input’s spectral overlap weights; a high-overlap Hartree-Fock state explains the dominant ground-energy cell.
State preparation injection
Every kernel factory (Walk, QSVT, and Trotter) takes an optional
state_prep kernel with signature (qubits: cudaq.qview). Without it,
factories return @cudaq.kernel(state) circuits that load the input state
as data (the simulation-friendly form). With it, they return
zero-argument circuits — the system register is allocated in |0...0>,
state_prep runs on it, and the operation follows — directly sampleable
and fully synthesizable, with the statevector abstracted away from the caller:
@cudaq.kernel
def my_prep(qubits: cudaq.qview):
rx(0.37, qubits[0])
ry(-0.52, qubits[1])
kernel = walk.kernel(power=3, state_prep=my_prep) # zero-arg circuit
counts = cudaq.sample(kernel)
moment = walk.moment(None, 3, state_prep=my_prep) # hardware-path moment
Contract: state_prep acts only on the system register it is handed,
which arrives in |0...0> with width num_system — not verifiable at
factory time, so a mismatched prep fails at launch.
Hardware-shaped vs. simulation-only
cudaq.get_state is a simulator-only API, so nothing in pauli_lcu,
qubitization, or qsvt calls it. Statevector conveniences are isolated in
cudaq_algorithms.sim_utils:
from cudaq_algorithms import sim_utils as sim
good = sim.good_subspace(enc, state) # postselect the |0..0>-ancilla block
hpsi = sim.action(enc, psi) # (H/alpha)|psi>
out = sim.transform(transformer, psi, seq)
psi0 = sim.state_from(ket) # precision-aware cudaq.State
Walk.moment / moments stay in the library proper: they measure through
cudaq.observe, which is a hardware-legitimate path.
Escape hatch at every level: the module-level kernels compose inside user
kernels, with enc.kernel_args supplying the flattened arrays they take
as arguments. They live in their module namespaces — their names are too
generic for the package root — as
cudaq_algorithms.pauli_lcu.{prepare, select, apply, walk, adjoint_walk, apply_phase_sequence, ...}
and cudaq_algorithms.common_kernels.{reflect_about_zero, signal_phase, ...}.
Simulator selection
Tests and examples default to qpp-cpu and honor CUDA-Q’s standard
CUDAQ_DEFAULT_SIMULATOR variable (e.g. nvidia-fp64 for the GPU
statevector simulator). Use an fp64 target for the test suite — the
nvidia target is fp32 and misses the 1e-8..1e-10 tolerances (precision,
not correctness). State construction goes through state_from, which
matches the input dtype to the active target’s precision (cudaq.complex()),
since fp32 simulators reject complex128 initial-state data. Pass
num_qubits=encoding.num_system to have it check the width: a
state-taking kernel allocates whatever register the data implies, so an
oversized ket would silently widen the system and an undersized one fail
inside the simulator.