Fermionic basis changes
fermion_basis_change constructs a number-preserving transformation of
fermionic modes and applies it to an existing quantum register. A square
unitary specifies the full transformation; a normalized vector specifies
one column, including its phase. It lives in
cudaq_algorithms.basis_change.
Conventions
The input is a matrix over spin-orbital modes, one mode per qubit: m
modes on m qubits placed by mode_map. It does not lift a spatial
matrix to both spin sectors. For a real orthogonal spatial rotation
applied to both spins of the interleaved layout, use the orbital-rotation
network in State preparation (stateprep.make_orbital_rotation_schedule
and stateprep.spatial_givens_network), or pass np.kron(V,
np.eye(2)) here. The network realizes V D with the schedule’s sign
diagonal D; np.kron(V @ np.diag(schedule.signs), np.eye(2))
reproduces it exactly.
Each mixing gate rotates two modes (first, second) by
[[cos θ, -sin θ], [sin θ, cos θ]], that is
exp(θ (a†_second a_first - a†_first a_second)). For adjacent modes
(second == first + 1) this is the same gate as
stateprep.givens_rotation(qubits, θ, first, second). On spatial modes
(mode, mode + 1) of the interleaved layout it equals
stateprep.spatial_givens_rotation(system, -θ, mode), which rotates
both spin sectors at once.
For an m by m unitary U, the circuit implements the
vacuum-preserving second quantization
Mode j lives on qubit mode_map[j] (qubit j by default) with
the usual Jordan-Wigner parity string over all lower-numbered qubits.
Qubits that mode_map skips are spectators: modes that U leaves
unchanged. To predict amplitudes, embed U in the identity on the whole
register, U_phys[np.ix_(mode_map, mode_map)] = U. For occupied sets
S and T of the same size, each sorted by qubit index, the
amplitude from T to S is det(U_phys[np.ix_(S, T)]).
Fixed transformations
import numpy as np
import cudaq
from cudaq_algorithms import fermion_basis_change
U = np.array([[1., -1.], [1j, 1j]]) / np.sqrt(2.)
plan = fermion_basis_change(U)
apply_basis = plan.kernel()
undo_basis = plan.adjoint_kernel()
@cudaq.kernel
def fixed_change(enable: cudaq.qubit, system: cudaq.qview):
cudaq.control(apply_basis, enable, system)
The factory accepts shapes (m, m), (m,), and (m, 1) with
m >= 2; for a single mode apply r1 directly. The input is a
one-particle matrix or vector, not a qubit unitary or a many-body state.
Input that is nonunitary or unnormalized beyond tolerance (default
1e-12) is rejected; schedule.reconstruction_error reports the
residual of an accepted inexact input.
A vector v gives a deterministic unitary completion W_v with
reference column v. The caller first prepares the reference
occupation:
vector = np.array([1., 1j]) / np.sqrt(2.)
partial = fermion_basis_change(vector)
prepare_column = partial.kernel()
@cudaq.kernel
def prepare_vector():
system = cudaq.qvector(2)
x(system[0])
prepare_column(system)
GivensStructure.partial(m, reference_mode=r) chooses another reference
mode, and GivensStructure.full(m) a full transformation. Either
accepts a mode_map of distinct physical qubits in logical mode order;
a mapped partial plan expects its reference occupation on qubit
mode_map[reference_mode].
controlled_kernel() takes one register with the enable at index zero
and the base layout shifted by one (plan.num_qubits + 1 qubits). The
Clifford scaffold around each rotation cancels when the enable is off, so
only the Rz and R1 gates are controlled. cudaq.control of kernel(),
as above, gives the same operator but controls every gate.
Warning
A view narrower than num_qubits (num_qubits + 1 for
controlled_kernel) is not rejected. CUDA-Q does not bounds-check
views, so the kernel silently addresses the parent-register qubits that
follow the view, such as a QROM address or scratch qubit.
Programmable plans
A fixed plan with an external control covers one transformation. To select among transformations with a quantum address, use a programmable plan: one circuit whose angles are read from quantum words, for example loaded by QROM.
from cudaq_algorithms.basis_change import GivensStructure
program = fermion_basis_change(U, programmable=True, angle_bits=8)
consume_words = program.kernel()
codes = program.encoded_words # (0, 64, 32, 64): the words for U
A consumer can also be built from a structure alone, with no matrix. It
has no host angles (encoded_words is None), so every angle comes
from the loaded words, typically a QROM table filled with other plans’
encoded_words:
structure = GivensStructure.partial(3, mode_map=(0, 2, 4))
consumer = fermion_basis_change(structure=structure,
programmable=True, angle_bits=8)
These two snippets are sized for illustration: at eight bits
program.num_qubits is 34 and consumer.num_qubits is 45, more than
a state-vector simulator can hold. The runnable example uses three bits.
Each word is an unsigned little-endian full-turn fixed-point angle of
b = angle_bits bits, from 1 through 52:
Full schedules have m*m slots and partial schedules 2*m-1; every
slot is read from its word, including slots whose host value is zero.
The kernel takes one combined register. The system span is
max(mode_map) + 1, and by default the words follow it contiguously in
schedule.parameter_names order. Explicit parameter_registers give
one list of angle_bits distinct qubit indices per slot,
least-significant bit first, outside the system span; they need not be
contiguous. num_qubits is the combined span; QROM addresses, scratch
and controls are additional.
Accuracy
A programmable plan reports its angle-rounding error as
plan.quantization_error_bound (classical plans round nothing and
report None). Two other errors are kept separate:
schedule.reconstruction_error is how far the compiled angles are from
an inexact input, and synthesis error is what your compiler adds when it
turns each Rz and R1 into native gates. To include synthesis, give each
rotation a spectral error eps (including global phase) and multiply
by the rotation count:
from cudaq_algorithms.basis_change import (
estimate_fermion_basis_change_error,
estimate_fermion_basis_change_resources)
eps = 1e-3
resources = estimate_fermion_basis_change_resources(program)
report = estimate_fermion_basis_change_error(
program.schedule, program.represented_parameters,
synthesis_error_bound=resources.num_bit_controlled_rotations * eps)
For a classical plan use num_elementary_rotations and
plan.schedule.parameters. report.basis_change_error_bound bounds
the whole transformation, and report.reflection_error_bound bounds a
reflection conjugated by it, which is twice the basis-change bound; both
are clipped at two.
Before building a plan, nearest rounding gives the a priori bound
Two is the largest spectral-norm distance between two unitaries, so this
bound says nothing once C*pi/2**b >= 2: for example, every full plan
with m >= 3 at angle_bits=4. A plan’s quantization_error_bound
adds up its actual rounding errors instead, so it is never larger and
usually smaller: for random 3-mode unitaries at four bits it is typically
0.8 to 1.6, while the actual Fock-space error is typically 0.2 to 0.6.
Selecting with QROM
The plan owns no QROM object. The caller packs each plan’s
encoded_words into table rows, constructs QROM, and composes
lookup, consumer, and inverse lookup; the inverse lookup restores the
words and scratch to zero. Rows sharing a consumer must share its
structure and encoding. With the default layout, a row is
sum(code << (angle_bits * s) for s, code in enumerate(codes)),
written to the output view q[base:consumer.num_qubits] with
base = consumer.structure.num_system_qubits and output_bits equal
to consumer.num_qubits - base; for controlled_kernel shift the view
by one. The runnable example on the
chemistry-primitive examples page does this for a fixed, a
controlled and a selected transformation.
For explicit parameter_registers, choose base from the system span
through the lowest word qubit and pack each row against the consumer’s
layout:
def pack_row(codes, consumer, base):
return sum(((code >> i) & 1) << (index - base)
for code, word in zip(codes, consumer.parameter_registers)
for i, index in enumerate(word))
The selected occupation reflection \(Q_j = W_j Z_r W_j^\dagger\) is
lookup, plan.adjoint_kernel(), Z on qubit mode_map[r],
plan.kernel(), and inverse lookup, where r is the reference mode of
a partial plan or a chosen mode of a full plan. Padded addresses with an
all-zero row still apply Z; control it on address validity if they
must act as identity.
Resources
estimate_fermion_basis_change_resources(plan) counts the static tape
of a plan, including zero-valued slots; it also accepts a schedule with
angle_bits and num_program_qubits, where an explicit layout needs
num_program_qubits=plan.num_qubits - plan.structure.num_system_qubits.
Each Givens uses two Pauli rotations; at physical endpoint separation
d its Jordan-Wigner scaffold uses 4*d CNOTs, eight Hadamards, and
four S/S-dagger gates. Each number phase is one rotation. Programmable
plans use bit-controlled Rz and R1 gates. The counts exclude QROM and
external controls.
controlled_kernel adds the enable to each rotation only: each Rz and
R1 becomes controlled, and a programmable plan’s bit-controlled rotations
become doubly controlled. cudaq.control of kernel() also controls
every Hadamard and S gate and turns each parity CNOT into a Toffoli.
Compare QROM selection against the controlled counts of the path you use.
Selected orbital reflections and precision
The runnable example uses the full two-mode fixture above and a partial
program with reference mode zero and three words (2*m-1).
A quantum address in (|0> + i|1>)/sqrt(2) selects the columns
[1, 0] and [1, i]/sqrt(2). Chronologically, it runs lookup,
inverse basis change, Z on the reference occupation, forward basis
change, and inverse lookup. Its operator is
For two modes the full Fock matrix is diag(1, U, det(U)) in
vacuum/mode-0/mode-1/both order. The example checks the reflection against
both this construction and independent Jordan-Wigner ladder matrices.
Its complex input has support in every particle sector; complete-state
comparisons preserve the address phase and detect residual words/ladder.
To control the reflection, control only the middle Z. The lookup and
basis-change pairs cancel on the inactive branch, including its phase.
This controls the whole reflection; controlled_kernel() controls a
basis change. The example executes enable zero, one, and a coherent enable.
The off-grid column [cos(0.47), exp(0.61j)*sin(0.47)] is executed at
three and four bits. NumPy reconstructs the represented matrix from
decoded words and public chronological operation metadata. The circuit
is compared tightly to that represented reflection. Ideal/represented
spectral and state errors are reported separately and checked against the
public reflection-error bound, which is twice the basis-change bound. For
this column the spectral error is 0.640 at three bits (bound 0.982) and
0.203 at four bits (bound 0.505); the three-bit error already exceeds the
plan’s basis-change bound of 0.491, so the factor of two is needed.
Higher precision improves the worst-case bound; individual rounding
errors need not decrease at every width. tolerance validates host
input, not gate-synthesis accuracy.
The full fixture has four words and twelve angle qubits at three bits, using sixteen qubits including address and scratch. The partial fixture has nine angle qubits at three bits, thirteen total, or fourteen with an enable; at four bits these totals are sixteen and seventeen. Widths come from the objects. Consumer resource estimates exclude the lookup, the inverse lookup, external enables, and native rotation synthesis.
Literature and scope
Programmable rotations and basis-transformed fermion operators motivate this composition: von Burg et al., Phys. Rev. Research 3, 033055 (2021), arXiv:2007.14460, supplementary VII B.1 and VII C.1–C.3; Lee et al., PRX Quantum 2, 030305 (2021), arXiv:2011.03494, Appendix C.2, Figure 16. This isolates lookup, programmable basis change, occupation reflection, and inverse lookup. It does not reproduce the complete chemistry algorithms, nested preparations, or their optimized costs.