State preparation

State preparation is an input to the library’s algorithms, not an algorithm in itself: every preparation here is (or can be packaged as) a CUDA-Q kernel taking the qubit register as its only argument (qubits: cudaq.qview), which makes it directly injectable into the algorithm factories via their state_prep= parameter — the block-encoding factories (Block encodings), the Trotter primitive (Trotter (product-formula simulation)), and qubitization / QSVT (Qubitization and QSVT) all accept it. See State preparation injection below for the shared contract.

Everything is exposed through the cudaq_algorithms.stateprep namespace: unitary-coupled-cluster (UCC) ansatz kernels, operator pools and Pauli-list converters, Hartree-Fock reference determinants, fixed-parameter UCC products, and Givens-rotation Slater determinants — all pure Python, requiring only the cudaq package.

The runnable examples are hartree_fock_ucc.py (fixed-parameter UCCSD vs. dense matrix exponentials) and givens_slater_determinant.py (Slater determinants) on the state-preparation examples page.

Ansatz kernels and operator pools

The uccsd (unitary coupled cluster with singles and doubles), uccgsd (generalized singles and doubles), upccgsd (paired generalized doubles), and ceo (coupled exchange operator) device kernels are @cudaq.kernel functions, composable from user kernels:

import cudaq
from cudaq_algorithms import stateprep

@cudaq.kernel
def ansatz(thetas: list[float], num_electrons: int, spin: int):
    qubits = cudaq.qvector(num_qubits)
    for i in range(num_electrons):
        x(qubits[i])                    # Hartree-Fock reference
    stateprep.uccsd(qubits, thetas, num_electrons, spin)

uccsd computes its excitation indices inline; its parameter order is fixed by get_uccsd_excitations (singles alpha, singles beta, mixed doubles, alpha doubles, beta doubles), and thetas must hold get_num_uccsd_parameters(num_qubits, num_electrons, spin) entries.

uccgsd, upccgsd, and ceo instead consume grouped Pauli data — one variational parameter per group — produced on the host:

words, coeffs = stateprep.get_uccgsd_pauli_lists(num_qubits)
stateprep.uccgsd(qubits, thetas, words, coeffs)      # inside a kernel

stateprep.get_upccgsd_pauli_lists(num_qubits, only_doubles=False)
stateprep.get_ceo_pauli_lists(num_orbitals)          # spatial orbitals!

The pools themselves are available as cudaq.SpinOperator lists for ADAPT-style workflows or custom conversion:

stateprep.make_uccsd_operator_pool(num_qubits, num_electrons, spin=0)
stateprep.make_uccgsd_operator_pool(num_qubits, only_singles=False,
                                    only_doubles=False)
stateprep.make_upccgsd_operator_pool(num_qubits, only_doubles=False)
stateprep.make_ceo_operator_pool(num_orbitals)       # spatial orbitals!

Device kernels have no error channel, so they perform no input validation — the host helpers are where the contracts are enforced.

Hartree-Fock references and fixed-parameter UCC

The reference determinant those ansatz kernels are applied to, plus a non-variational UCC product on top of it (amplitudes fixed by, e.g., a classical pre-optimization — no optimizer in the loop):

# Device kernels, composable from user kernels:
stateprep.hartree_fock(qubits, num_electrons)             # closed shell
stateprep.hartree_fock_occupation(qubits, occupied)       # explicit/open shell
stateprep.fixed_parameter_ucc(qubits, thetas, words, coeffs)

# Host helpers:
occ = stateprep.make_hartree_fock_occupation(num_qubits, num_electrons,
                                             spin=2)
stateprep.validate_hartree_fock_occupation(num_qubits, occ)

pool = stateprep.make_uccsd_operator_pool(num_qubits, num_electrons)
words, coeffs = stateprep.get_fixed_parameter_ucc_pauli_lists(
    pool, num_qubits)                  # works for ANY operator pool
stateprep.validate_fixed_parameter_ucc(num_qubits, thetas, words, coeffs)

make_hartree_fock_occupation builds the occupied spin-orbital list: contiguous {0, ..., num_electrons - 1} for closed shell, and for spin > 0 the interleaved alpha (even) / beta (odd) layout of get_uccsd_excitations — e.g. 4 electrons at spin 2 occupy {0, 1, 2, 4}, not {0, 1, 2, 3} — so the reference lines up with a UCCSD pool built at the same spin.

get_fixed_parameter_ucc_pauli_lists converts any operator pool to the grouped form the kernel takes, dropping terms with |coefficient| <= coefficient_tolerance and rejecting complex coefficients (exp_pauli angles are real).

The hartree_fock_ucc_kernel factory

The packaged form: a (qubits: cudaq.qview) kernel preparing the reference determinant and applying the fixed-amplitude UCC product — directly injectable as a state_prep kernel.

prep = stateprep.hartree_fock_ucc_kernel(
    num_qubits, parameters, words, coeffs,
    num_electrons=num_electrons, spin=0)      # canonical reference
prep = stateprep.hartree_fock_ucc_kernel(
    num_qubits, parameters, words, coeffs,
    occupied_orbitals=[0, 1, 2, 4])           # explicit reference

Provide exactly one of num_electrons (with optional spin) or occupied_orbitals. The returned kernel expects a num_qubits-wide register in |0...0>. Validation runs at factory time; the grouped data is flattened into per-rotation angles before capture (nested lists marshal as kernel arguments but cannot be closure-captured), and empty occupation/rotation lists select a kernel shape with no empty captures (an empty list cannot cross the kernel boundary).

Resource estimation

stateprep.estimate_hartree_fock_resources(num_qubits, num_electrons,
                                          spin=0)
stateprep.estimate_hartree_fock_occupation_resources(num_qubits, occ)
# -> HartreeFockResourceEstimate(num_qubits, num_electrons, num_x_gates)

stateprep.estimate_fixed_parameter_ucc_resources(num_qubits, words)
# -> FixedParameterUccResourceEstimate(num_qubits, num_excitations,
#        num_pauli_rotations, max_pauli_rotations_per_excitation)

Like TrotterResourceEstimate, these are frozen dataclasses counting logical operations before transpilation, not hardware gate counts.

Givens-rotation Slater determinants

Prepares the Slater determinant of an orthonormal occupied-orbital matrix Q (num_spin_orbitals x num_electrons) on the Jordan-Wigner / little-endian layout: the amplitude of basis state |S> with occupied set S is det(Q[S, :]), up to a global phase. The construction is that of Jiang et al., Phys. Rev. Applied 9, 044036 (2018) (arXiv:1711.05395, Sec. III), with the strictly adjacent, linear-depth rotation scheduling of Kivlichan et al., Phys. Rev. Lett. 120, 110501 (2018) (arXiv:1711.04789).

schedule = stateprep.make_givens_rotation_schedule(orbital_coefficients)
schedule.num_spin_orbitals, schedule.num_electrons, schedule.is_complex
schedule.rotations                    # adjacent rotations, application order
schedule.final_phases                 # one per electron (complex only)

prep = stateprep.slater_determinant_kernel(schedule)   # (qubits: qview)

stateprep.estimate_givens_resources(schedule)  # GivensResourceEstimate

make_givens_rotation_schedule reduces Q to the computational-basis determinant with adjacent (nearest-neighbor) Givens row rotations on the host; the kernels apply the inverse rotations in reverse order to the determinant |1...10...0>. Real and complex matrices dispatch automatically (a complex dtype routes complex even when every value is real); complex schedules carry a relative phase per rotation plus one final phase per electron. validate_givens_rotation_schedule guards hand-built schedules; built schedules always pass.

slater_determinant_kernel(schedule) is the packaged, injectable form. The module-level device kernels remain composable from user kernels, with get_givens_rotation_indices / ..._angles / ..._phases supplying the flattened arrays that cross the kernel boundary:

stateprep.slater_determinant(qubits, indices, angles, num_electrons)
stateprep.complex_slater_determinant(qubits, indices, angles, phases,
                                     final_phases, num_electrons)
stateprep.givens_rotation(qubits, theta, first, second)         # adjacent
stateprep.phase_givens_rotation(qubits, theta, phase, first, second)

estimate_givens_resources returns a GivensResourceEstimate (num_givens_rotations, num_exp_pauli_calls, num_phase_rotations, two_qubit_gate_count_proxy, depth_proxy) — decomposition-independent proxies, not transpiled gate counts.

Orbital rotations

The same module compiles a real orthogonal one-particle matrix V (n x n, target modes as columns) to an adjacent Givens network on spatial modes, applied to both spin sectors of the interleaved layout (mode p on qubits 2p and 2p + 1). This is the basis change RotatedEncoding.from_orbital_rotation and the double-factorized example conjugate their encodings with:

schedule = stateprep.make_orbital_rotation_schedule(V)
schedule.rotations            # (mode, theta) on modes (mode, mode + 1)
schedule.signs                # residual +-1 per mode: the network gives V D

modes, angles = stateprep.orbital_rotation_program(schedule, inverse=False)
stateprep.spatial_givens_network(system, modes, angles)   # realizes V D
stateprep.spatial_givens_rotation(system, theta, mode)    # one rotation

make_orbital_rotation_schedule zeroes each column’s sub-diagonal with rotations of adjacent rows, bottom-up, leaving a diagonal of signs D; orbital_rotation_program turns the schedule into the flattened lists the network kernel takes, inverse=False realizing V D and inverse=True its transpose. The sign per mode is immaterial for operators diagonal in the rotated modes; RotatedEncoding.from_orbital_rotation cancels it with a Z on both spin orbitals of each such mode (mode_signs reports it), so its frame kernels realize V exactly. For a diagonal V the program is the single zero-angle rotation [0], [0.0]: an identity on any register, including a single spatial mode (two qubits), so no empty list crosses the kernel boundary. spatial_givens_segment applies count rotations from start of a flat list shared by several frames.

Here an n x n real orthogonal matrix is spatial: it acts on n modes, each on two qubits, identically in both spin sectors. A matrix over spin-orbital modes, one per qubit and possibly complex, is the input of Fermionic basis changes, which also places modes on arbitrary qubits and accepts quantum angle words; fermion_basis_change(np.kron(V, np.eye(2))) realizes V itself, without the residual D, on both spins of the interleaved layout. The rotation conventions agree: givens_rotation(qubits, theta, first, second) is that page’s mixing gate at theta on adjacent modes (first, first + 1), and spatial_givens_rotation(system, theta, mode) is its mixing gate at -theta on spatial modes (mode, mode + 1), rotating both spin sectors at once.

State preparation injection

Every kernel factory in the package family — PauliLCU.encode_kernel, Walk.kernel (and its adjoint/controlled variants), QSVT.kernel, and Trotter.kernel — takes an optional state_prep kernel with signature (qubits: cudaq.qview). The returned circuit is then zero-argument: 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 (a simulator still uses one internally).

Any (qubits: cudaq.qview) preparation qualifies, including the factory outputs of this package — hartree_fock_ucc_kernel(...) and slater_determinant_kernel(...) — and the raw kernels wrapped by the caller:

import cudaq
from cudaq_algorithms import PauliLCU, Trotter, stateprep

pool = stateprep.make_uccsd_operator_pool(4, 2)
words, coeffs = stateprep.get_fixed_parameter_ucc_pauli_lists(pool, 4)
prep = stateprep.hartree_fock_ucc_kernel(4, [0.11, -0.04, 0.28], words,
                                         coeffs, num_electrons=2)

hamiltonian = {"ZIII": 0.5, "IZII": 0.5, "XXII": 0.25}

# Trotter time evolution from the UCC state:
kernel = Trotter(hamiltonian).kernel(time=0.8, steps=4, state_prep=prep)
counts = cudaq.sample(kernel)

# The same prep drives the block-encoding/walk/QSVT factories:
enc = PauliLCU(hamiltonian)
kernel = enc.encode_kernel(state_prep=prep)

Contract (shared with the other primitives): state_prep acts only on the system register it is handed, which arrives in |0...0> with the factory’s system width (num_qubits for Trotter, num_system for the encodings) — not verifiable at factory time, so a mismatched prep fails at launch. The stateprep factories bake their width in at construction (num_qubits for hartree_fock_ucc_kernel, num_spin_orbitals for slater_determinant_kernel), so build them to match. tests/python/test_state_prep_injection.py exercises the contract end-to-end.

Package conventions

  • Qubit layout: interleaved spin orbitals — alpha spin orbitals on even qubits, beta on odd (spatial orbital i maps to qubits 2i / 2i + 1). All pools, excitation enumerations, and Hartree-Fock occupations share it.

  • `spin` semantics: spin is the difference between alpha and beta electron counts (twice the total S_z), so n_beta = (num_electrons - spin) // 2 and n_alpha = num_electrons - n_beta. spin == 0 selects the closed-shell forms; spin > 0 requires an even num_qubits and produces the interleaved open-shell occupations and excitations.

  • Error types: every input guard raises ValueError. get_uccsd_excitations and make_hartree_fock_occupation apply the same (num_qubits, num_electrons, spin) checks with the same messages; in particular both reject an odd num_electrons - spin when spin > 0, since the beta floor would otherwise silently realize spin + 1.

  • CEO orbital counts: the CEO helpers (make_ceo_operator_pool, get_ceo_pauli_lists) take num_orbitals in spatial orbitals — the pool acts on 2 * num_orbitals qubits. Everything else in the package counts qubits (spin orbitals).

See Conventions and Reference for the library-wide qubit-ordering, Pauli-word, and integral-tensor conventions these build on.