C.3 Python and C++ interface
On this page · Permalink · Source line 286
C.3.1 Package overview
On this page · Permalink · Source line 290
The Python package catalytic_gate_atlas exports exact primitives for the linear, Clifford, and classical reversible experiments. It requires Python 3.10 or later and has no runtime dependencies.
C.3.2 Installation
On this page · Permalink · Source line 293
cd code
python -m venv .venv
. .venv/bin/activate
python -m pip install -e . --no-build-isolation
python -m pytest testsOn Windows PowerShell, activation is
.\.venv\Scripts\Activate.ps1C.3.3 Top-level API
On this page · Permalink · Source line 306
from catalytic_gate_atlas import (
RowGate,
canonical_ambient_word,
canonical_restricted_word,
canonical_six_target,
snapshot_target,
verify_canonical_atom,
exact_clifford_census,
exact_affine_toffoli_census,
gate_word_to_openqasm,
)C.3.4 Linear atom
On this page · Permalink · Source line 321
from catalytic_gate_atlas import verify_canonical_atom
for modulus in (2, 3, 5, 8):
print(verify_canonical_atom(modulus))The function evaluates the displayed restricted and ambient words over \({\mathbb Z}/m{\mathbb Z}\) and compares both endpoints with the canonical target.
C.3.5 Snapshot targets
On this page · Permalink · Source line 330
from catalytic_gate_atlas import snapshot_target
# u=4 source updates; snapshots at phases 0, 2, and 4.
A = snapshot_target(4, phases=(0, 2, 4), modulus=2)
for row in A:
print(row)The generator checks phase order and produces the exact lower-unitriangular target matrix used in the symbolic family.
C.3.6 Clifford census
On this page · Permalink · Source line 341
from catalytic_gate_atlas import exact_clifford_census
print(exact_clifford_census(2, entangling_cost=True))
print(exact_clifford_census(2, entangling_cost=False))The optional three-qubit Python census is slower. The release includes an optimized C++ program for the full \(1{,}451{,}520\)-state group.
C.3.7 Affine-versus-Toffoli census
On this page · Permalink · Source line 350
from catalytic_gate_atlas import exact_affine_toffoli_census
print(exact_affine_toffoli_census(3, entangling_cost=False))
print(exact_affine_toffoli_census(3, entangling_cost=True))The complete ambient enumeration is intentionally limited to three bits.
C.3.8 OpenQASM witness export
On this page · Permalink · Source line 359
from catalytic_gate_atlas import gate_word_to_openqasm
word = ["H1", "CX12", "CX21", "CX20", "CX02", "H0"]
print(gate_word_to_openqasm(word, 3, title="ambient witness"))The exporter supports the named \(H\), \(S\), \(X\), CX, CZ, and SWAP gates used by the finite atlas and writes OpenQASM 3. The supplied files in examples/ encode the two- and three-qubit restricted and ambient witness words. The Clifford census is performed modulo global phase and Pauli translations, so equality of an exported pair refers to its binary symplectic action unless the ignored Pauli and phase data are separately reconstructed.
PYTHONPATH=. python scripts/export_qasm_examples.pyC.3.9 Search primitives
On this page · Permalink · Source line 372
from catalytic_gate_atlas.search import (
NamedGenerator,
breadth_first_distances,
breadth_first_with_parents,
zero_one_distances,
zero_one_with_parents,
dijkstra_distances,
reconstruct_path,
defect_distribution,
)Every state must be immutable and hashable. The caller supplies a multiplication function with the convention
C.3.10 Binary matrix primitives
On this page · Permalink · Source line 390
The module algebra.py provides:
gf2_identity,gf2_mul,gf2_transpose,gf2_rank,dense modular matrix multiplication,
exact permutation composition and inversion.
C.3.11 C++ verifier
On this page · Permalink · Source line 401
g++ -O3 -std=c++20 scripts/clifford_census.cpp -o scripts/clifford_census
./scripts/clifford_census --n 3 --metric total
./scripts/clifford_census --n 3 --metric total --swap
./scripts/clifford_census --n 3 --metric entanglingThe executable can write JSON using the --output option.
C.3.12 Figure generation
On this page · Permalink · Source line 410
python scripts/make_monograph_figures.pyAll new monograph figures are generated by Matplotlib without external data. The established unitriangular figures are preserved from the Paper I source archive.
C.3.13 Adding a new finite gate model
On this page · Permalink · Source line 416
A new module should implement:
a canonical immutable state representation;
exact multiplication;
named restricted and ambient generators with nonnegative costs;
an exact target-membership test;
a census function returning the standard JSON fields;
smoke tests for group size and witness evaluation.
C.3.14 Standard result schema
On this page · Permalink · Source line 427
A census result should include:
{
"model": "descriptive-name",
"size": n,
"metric": "total-or-weighted",
"restricted_group_size": ...,
"ambient_group_size": ...,
"restricted_diameter": ...,
"ambient_diameter": ...,
"defect_count": ...,
"defect_distribution": {...},
"maximum_defect": ...,
"witness": {...},
"status": "complete finite enumeration"
}A partial search must not use the status string “complete finite enumeration.”
C.3.15 Error handling
On this page · Permalink · Source line 447
Several entry points validate dimensions, distinct controls, matrix shape, and cost restrictions. The complete affine census rejects widths above three, and the C++ Clifford executable accepts only one through three qubits. Low-level helpers assume well-formed indices and states, so callers should not treat every helper as a fully validated public parser. The search code does not silently truncate its reachable state space.