Chemistry-primitive examples
Fermionic transformations applied to an existing register, each checked against its exact state.
See also
Chemistry primitives — the primitives behind these examples.
Fermionic basis changes with explicit QROM
Applies a fixed two-mode basis change, enables it with an external
control, and then selects between two transformations with a quantum
address: a QROM lookup loads the angle words, the programmable plan
consumes them, and the inverse lookup clears them. The same script then
builds coherently selected orbital reflections from a partial program and
compares three- and four-bit angle words. See
Fermionic basis changes.
"""Fixed, QROM-programmed and selected-reflection fermionic basis changes.
Fermionic simulation often becomes simpler after mixing the orbital modes into
a different basis. A Givens rotation performs one such mixing between a pair
of modes while preserving particle number. This example first applies a fixed
basis change, then shows how a quantum address can load angle words from QROM
so one programmable circuit performs the transformation selected by that
address.
You should learn the difference between enabling a fixed operation and
supplying its parameters as quantum data. A selected-orbital reflection then
transforms into the chosen orbital basis, marks occupation with a sign, and
transforms back, providing a useful building block for chemistry encodings.
Complete-state NumPy checks follow the address phases, particle sectors, and
cleared angle/scratch registers. Comparing two angle precisions shows how a
represented transformation can match its circuit closely while still
approximating the desired transformation.
Run: python3 fermion_basis_change.py. Uses fp64 qpp-cpu by default.
The full two-mode fixture uses sixteen qubits; partial programs use three
angle words instead of four. All references include every particle sector.
Add --verbose to show individual validation checks; failures are always reported.
"""
import argparse
import os
import cudaq
import numpy as np
from cudaq_algorithms import fermion_basis_change, state_from
from cudaq_algorithms.basis_change import (
GivensStructure, estimate_fermion_basis_change_resources)
from cudaq_algorithms.primitives import QROM
ATOL = 1e-10
def bound_check(label, error, tolerance, *, verbose=False):
passed = np.isfinite(error) and error <= tolerance
if verbose or not passed:
print(f"CHECK {label}: {error:.3e} <= {tolerance:.3e} -> "
f"{'PASS' if passed else 'FAIL'}")
if not passed:
raise AssertionError(label)
def check(label, actual, expected, *, verbose=False):
bound_check(label,
float(np.max(np.abs(actual - expected))),
ATOL,
verbose=verbose)
def full_transformations(*, verbose=False):
print("Fixed/externally controlled transformations use classical angles; "
"QROM-selected transformations consume caller-owned quantum words.")
# A 2x2 mode matrix acts on TWO occupation qubits. Its full Fock action
# preserves vacuum, acts as U on one particle, and as det(U) on two particles.
U = np.array([[1., -1.], [1j, 1j]]) / np.sqrt(2)
fixed = fermion_basis_change(U)
apply_fixed = fixed.kernel()
# H on both qubits gives amplitude 1/2 on every Fock state.
@cudaq.kernel
def fixed_demo():
system = cudaq.qvector(2)
h(system[0])
h(system[1])
apply_fixed(system)
fock = np.zeros((4, 4), dtype=complex)
fock[0, 0] = 1
fock[1:3, 1:3] = U
fock[3, 3] = np.linalg.det(U)
check("fixed full Fock action",
np.asarray(cudaq.get_state(fixed_demo)),
fock @ (np.ones(4) / 2),
verbose=verbose)
# An external enable can coherently control the same fixed transformation.
# The returned wrapper expects [enable, system...]. Its angles stay classical.
controlled_fixed = fixed.controlled_kernel()
@cudaq.kernel
def controlled_demo():
q = cudaq.qvector(3)
h(q[0])
h(q[1])
h(q[2])
controlled_fixed(q)
# The enable is qubit 0: even indices (enable=0) keep the uniform two-mode
# state, odd indices (enable=1) carry the full Fock action.
uniform = np.ones(4) / (2 * np.sqrt(2))
expected_controlled = np.zeros(8, dtype=complex)
expected_controlled[0::2] = uniform
expected_controlled[1::2] = fock @ uniform
check("controlled fixed Fock action",
np.asarray(cudaq.get_state(controlled_demo)),
expected_controlled,
verbose=verbose)
# Now choose I or U using a quantum address. Both matrices share one Givens
# structure, so one programmable circuit can consume either word string.
# QROM is one way to load those words.
bits = 3
plans = [
fermion_basis_change(matrix, programmable=True, angle_bits=bits)
for matrix in (np.eye(2), U)
]
program = plans[0]
if any(p.structure != program.structure for p in plans):
raise AssertionError("table rows must share one Givens structure")
if [p.encoded_words for p in plans] != [(0, 0, 0, 0), (0, 2, 1, 2)]:
raise AssertionError("unexpected angle words for I and U")
# Four slots: diagonal phases, mixing angle, relative phase. Keep zero slots:
# the loaded quantum words override every slot, including host zero angles.
# With the default layout and the output view q[2:span], slot s starts at
# output bit bits*s; other layouts use parameter_registers (see the guide).
rows = [
sum(code << (bits * slot) for slot, code in enumerate(p.encoded_words))
for p in plans
]
table = QROM(rows,
address_bits=1,
output_bits=bits * program.structure.num_parameters,
variant="select")
lookup = table.kernel
consume = program.kernel()
span = program.num_qubits # 2 system + 4 slots * 3 bits = 14
address = span
scratch = address + table.num_address
total = scratch + table.num_ladder # 16, including address and QROM scratch
@cudaq.kernel
def selected_preparation():
q = cudaq.qvector(total)
h(q[0])
h(q[1])
h(q[address])
lookup(q[address:scratch], q[scratch:total], q[2:span])
consume(q[0:span])
lookup(q[address:scratch], q[scratch:total], q[2:span])
# Address 0 keeps the uniform two-mode state; address 1 applies the full
# Fock action of U, so all four loaded words and det(U) are observed.
# Compare the complete state, so nonzero angle/scratch outputs also fail.
expected = np.zeros(1 << total, dtype=complex)
expected[0:4] = uniform
expected[(1 << address):(1 << address) + 4] = fock @ uniform
state = np.asarray(cudaq.get_state(selected_preparation))
check("full QROM preparation/workspace", state, expected, verbose=verbose)
print("Selected preparation:",
[(i, complex(np.round(a, 3)))
for i, a in enumerate(state) if abs(a) > ATOL])
print("Register widths:", program.structure.num_system_qubits, "system +",
table.num_output, "angles +", table.num_address, "address +",
table.num_ladder, "scratch =", total)
print("Quantization bounds:", [p.quantization_error_bound for p in plans])
print("Fixed, controlled, and selected checks passed.")
def fock_two_modes(orbital):
"""Vacuum, mode 0, mode 1, both; vacuum phase is fixed to one."""
result = np.zeros((4, 4), dtype=complex)
result[0, 0] = 1
result[1:3, 1:3] = orbital
result[3, 3] = np.linalg.det(orbital)
return result
def reconstruct(plan, *, verbose=False):
"""Independent NumPy product of the public chronological metadata."""
angles = [plan.angle_encoding.decode(code) for code in plan.encoded_words]
result = np.eye(plan.structure.num_modes, dtype=complex)
for op in plan.schedule.operations:
theta = op.scale * angles[op.parameter_index]
gate = np.eye(len(result), dtype=complex)
if op.kind == "phase":
gate[op.first, op.first] = np.exp(1j * theta)
else:
c, s = np.cos(theta), np.sin(theta)
gate[np.ix_([op.first, op.second],
[op.first, op.second])] = [[c, -s], [s, c]]
result = gate @ result
check("decoded metadata vs schedule",
result,
plan.schedule.orbital_matrix(plan.represented_parameters),
verbose=verbose)
return result
def ideal_reflection(column, *, verbose=False):
"""Compare second quantization with independent JW creation matrices."""
# a0^dagger and a1^dagger, qubit zero least significant.
raise_ = np.array([[0., 0.], [1., 0.]])
creators = [
np.kron(np.eye(2), raise_),
np.kron(raise_, np.diag([1., -1.]))
]
b_dagger = sum(v * a for v, a in zip(column, creators))
jw = np.eye(4) - 2 * b_dagger @ b_dagger.conj().T
lifted = fock_two_modes(np.eye(2) - 2 * np.outer(column, column.conj()))
check("orbital reflection vs JW I-2b†b", lifted, jw, verbose=verbose)
return lifted
def selected_reflections(columns, bits, label, *, verbose=False):
"""Lookup, W†, Z_reference, W, inverse lookup; keeps the address phase."""
structure = GivensStructure.partial(2, reference_mode=0)
plans = [
fermion_basis_change(v,
structure=structure,
programmable=True,
angle_bits=bits) for v in columns
]
program = plans[0]
if structure.num_parameters != 3: # zero-valued slots are kept
raise AssertionError("a partial two-mode plan has three slots")
if any(p.structure != program.structure for p in plans):
raise AssertionError("table rows must share one Givens structure")
rows = [
sum(code << (bits * slot) for slot, code in enumerate(p.encoded_words))
for p in plans
]
table = QROM(rows,
address_bits=1,
output_bits=bits * structure.num_parameters,
variant="select")
lookup = table.kernel # property, unlike the plan's kernel factories
forward, inverse = program.kernel(), program.adjoint_kernel()
span = program.num_qubits
address = span
scratch = address + table.num_address
enable = scratch + table.num_ladder
represented, ideals = [], []
z_reference = np.diag([1., -1., 1., -1.])
for p, v in zip(plans, columns):
w = fock_two_modes(reconstruct(p, verbose=verbose))
represented.append(w @ z_reference @ w.conj().T)
ideals.append(ideal_reflection(v, verbose=verbose))
rng = np.random.default_rng(7)
ket = rng.normal(size=4) + 1j * rng.normal(size=4)
ket /= np.linalg.norm(ket) # vacuum and both particles carry phase too
address_amplitudes = np.array([1., 1j]) / np.sqrt(2)
for external, controls, description in ((False, [1.], "uncontrolled"),
(True, [1., 0.], "enable=0"),
(True, [0., 1.], "enable=1"),
(True,
[1 / np.sqrt(2), 1j / np.sqrt(2)
], "coherent enable")):
total = enable + int(external)
@cudaq.kernel
def reflect(state: cudaq.State):
q = cudaq.qvector(state)
lookup(q[address:scratch], q[scratch:enable], q[2:span])
inverse(q[0:span])
if external:
z.ctrl(q[enable], q[0])
else:
z(q[0])
forward(q[0:span])
# Inverse lookup. The XOR lookup is its own inverse, so the same
# call clears the words and the ladder.
lookup(q[address:scratch], q[scratch:enable], q[2:span])
initial = np.zeros(1 << total, dtype=complex)
expected = np.zeros_like(initial)
for control, amplitude in enumerate(controls):
for j, address_amplitude in enumerate(address_amplitudes):
indices = np.arange(4) + (j << address) + (control << enable)
weight = amplitude * address_amplitude
initial[indices] = weight * ket
operator = (np.eye(4)
if external and control == 0 else represented[j])
expected[indices] = weight * (operator @ ket)
actual = np.asarray(cudaq.get_state(reflect, state_from(initial)))
check(f"{label}, b={bits}, {description}, full state/workspace",
actual,
expected,
verbose=verbose)
resources = estimate_fermion_basis_change_resources(program)
print(
f"{label}: {structure.num_system_qubits} system + "
f"{resources.num_program_qubits} angle + {table.num_address} address + "
f"{table.num_ladder} ladder = {enable} qubits; "
f"external enable adds one ({total}); slots={structure.num_parameters}, "
f"radian step={program.angle_encoding.step:.6g}")
print(
f" consumer: {resources.num_bit_controlled_rotations} bit-controlled "
"rotations; excludes lookup, inverse lookup and external control")
for j, p in enumerate(plans):
error = float(np.linalg.norm(represented[j] - ideals[j], 2))
action_error = float(np.linalg.norm(
(represented[j] - ideals[j]) @ ket))
bound = p.quantization_error.reflection_error_bound
print(f" row {j}: words={p.encoded_words}; ideal/represented "
f"operator error={error:.6g}, action error={action_error:.6g}, "
f"reflection bound={bound:.6g}")
bound_check(f"{label}, b={bits}, row {j}, operator error within bound",
error,
bound + ATOL,
verbose=verbose)
bound_check(
f"{label}, b={bits}, row {j}, action error within operator",
action_error,
error + ATOL,
verbose=verbose)
def main():
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument(
"--verbose",
action="store_true",
help="show each validation check (failures are always reported)")
verbose = parser.parse_args().verbose
cudaq.set_target(os.environ.get("CUDAQ_DEFAULT_SIMULATOR", "qpp-cpu"))
full_transformations(verbose=verbose)
selected_reflections([np.array([1., 0.]),
np.array([1., 1j]) / np.sqrt(2)],
3,
"on-grid",
verbose=verbose)
off_grid = np.array([np.cos(.47), np.exp(.61j) * np.sin(.47)])
for bits in (3, 4):
selected_reflections([np.array([1., 0.]), off_grid],
bits,
"off-grid",
verbose=verbose)
print("All fixed, programmed and selected-reflection checks PASS.")
if __name__ == "__main__":
main()