Structural SLPC bond-schedule construction, GF(2) utilities, homology checks, and local detector discovery for CSS quantum error-correcting codes.
The v0.1 circuit emitter converts a supported CSS code's outer-qubit SLPC bond schedule into a Stim MPP circuit. It does not yet perform gadget expansion, detector annotation, logical preservation certification, or end-to-end fault-tolerance verification.
Release v0.1.0 is the supported structural API baseline. Install the exact
GitHub release wheel with:
python -m pip install \
https://github.com/jerrylvx/stim-floquet/releases/download/v0.1.0/stim_floquet-0.1.0-py3-none-any.whlRelease notes and source artifacts are at
https://github.com/jerrylvx/stim-floquet/releases/tag/v0.1.0. The package is
not currently published on PyPI. For development, use
python -m pip install -e ".[dev]".
Requires Python 3.10+ with stim>=1.12 and numpy>=1.24.
For 3-5x speedup on GF(2) hot paths (RREF, rank, nullspace), install the optional binar backend:
pip install -e ".[fast]"binar is a Rust/SIMD GF(2) library from microsoft/qdk-ec.
When installed, rank_gf2, nullspace_gf2, and rref_dense dispatch to it automatically.
import numpy as np
from stim_floquet import css_to_slpc_bond_circuit
# [[7,1,3]] Steane code
H_X = np.array([
[1, 0, 0, 1, 0, 1, 1],
[0, 1, 0, 1, 1, 0, 1],
[0, 0, 1, 0, 1, 1, 1],
], dtype=np.uint8)
H_Z = H_X.copy()
circuit = css_to_slpc_bond_circuit(H_X, H_Z, n_periods=3)
print(circuit)Output:
R 0 1 2 3 4 5 6
TICK
REPEAT 3 {
MPP Z0*Z6 Z2*Z5 Z3*Z4
TICK
MPP X0*X6 X2*X5 X3*X4
TICK
...
}
Given supported CSS parity-check matrices H_X and H_Z, stim-floquet can:
- Constructs an SLPC graph — the bipartite bond structure connecting X-checks to Z-checks through shared qubits.
- Colors the bonds — edge-colors the SLPC graph so no qubit is measured twice per round.
- Construct a structural schedule — assigns colored bonds to X/Z measurement rounds.
- Emit an MPP circuit — repeats that outer-qubit bond schedule in Stim.
- Verify tableau-compatible Clifford circuits — checks chain-map homology
for circuits supported by
stim.Circuit.to_tableau(). - Discover local detectors — finds bounded-temporal-span measurement relations and validates them by noiseless sampling.
An empty SLPC graph is rejected by the circuit emitter. The package does not currently claim support for every CSS code or verify that an emitted structural schedule realizes a complete fault-tolerant gadget construction.
from stim_floquet import (
css_to_slpc_bond_circuit, # H_X, H_Z → structural MPP circuit
build_floquet_schedule, # H_X, H_Z → FloquetSchedule
schedule_to_stim, # FloquetSchedule → stim.Circuit (single period)
multi_round_circuit, # FloquetSchedule → stim.Circuit (multi-period)
slpc_graph, # H_X, H_Z → GadgetGraph
color_bonds, # GadgetGraph → BondColoring
merge_schedule, # FloquetSchedule → MergeResult (depth optimization)
)Takes CSS parity-check matrices and returns a multi-period structural SLPC bond
circuit with reset initialization and MPP measurements. The former
css_to_floquet_circuit name remains as a deprecated compatibility alias.
Constructs the measurement schedule (bond coloring + round assignment) without emitting a circuit. Useful when you need to inspect or modify the schedule before circuit generation.
Builds the SLPC (Stabilizer-Logical Product Code) bipartite graph. Each edge represents a 2-body measurement bond between an X-check qubit and a Z-check qubit sharing a data qubit.
Optimizes schedule depth by merging compatible rounds (rounds whose measurements commute and share no qubits). With cross_basis=True, also attempts merging across X/Z basis boundaries.
from stim_floquet import (
verify_circuit_homology, # Full pipeline verification
verify_boundary_map, # Check: d2 @ x = g1 @ p2 @ x (mod 2)
verify_tableau_equality, # Check: composed tableau = full circuit tableau
verify_gf2_matrix_span, # Check: targets in span of basis (GF(2))
solve_mod2, # Solve Ax = b over GF(2)
)Verifies the chain-map homology structure of a tableau-compatible Clifford
circuit. Measurement-heavy MPP schedules emitted by
css_to_slpc_bond_circuit are not automatically passed through this verifier.
from stim_floquet import (
build_local_detector_basis, # stim.Circuit → LocalDetectorResult
windowed_local_detectors, # Nullspace projection onto time windows
incremental_detectors, # Online detector discovery from samples
local_subspace, # Project detector space onto a window mask
detectors_to_stim_lines, # Convert detectors to DETECTOR instructions
validate_detectors, # Verify detectors are valid (product = +I)
)Given a Stim circuit and its period size (measurements per round), discovers all detectors supported within a 2-period window. Returns detector tuples indexing measurement records.
Low-level: given the full detector space K (nullspace of the noiseless measurement matrix), projects onto sliding 2-period windows to extract temporally-local detectors.
Online algorithm: processes measurement samples chronologically and discovers detectors via running GF(2) elimination. When a new measurement is linearly dependent on previous ones, the reduction trail gives a detector.
from stim_floquet import (
rref_dense, # RREF over GF(2), returns (R, pivots)
rref_dense_with_transform,# RREF with transformation matrix
nullspace_gf2, # Kernel of a binary matrix
rank_gf2, # Rank over GF(2)
solve_gf2, # Solve Ax = b over GF(2) (SolveResult)
inverse_gf2, # Matrix inverse over GF(2)
is_invertible_gf2, # Invertibility check
as_gf2, # Coerce to uint8 mod 2
hyperbolic_decomposition, # Witt decomposition of symplectic space
omega, # Standard symplectic form [[0,I],[I,0]]
symplectic_inner_product, # Symplectic inner product of two vectors
symplectic_gram, # Gram matrix of symplectic form
)src/stim_floquet/
__init__.py # Public API re-exports
core/
__init__.py # Compatibility re-exports
gf2.py # GF(2) linear algebra implementation
gram_schmidt.py # Symplectic Gram-Schmidt (Witt decomposition)
tableau_bridge.py # Symplectic matrix <-> stim.Tableau
css_logicals.py # CSS logical operator extraction
synthesis/
__init__.py
slpc.py # SLPC graph construction
build.py # Gadget symplectic matrix synthesis
sync.py # Edge-coloring + schedule construction
bkrc.py # Bond-kernel rank condition
circuit.py # Structural bond schedule -> stim.Circuit
floquet_verifier.py # Chain map homology verification
local_detectors.py # Local detector basis discovery
pytest tests/ -v # 74 passed, 1 skipped in the v0.1 release checkThis repository is the source of truth for local detector discovery. As of
v0.1.0, auto_detector pins stim-floquet==0.1.0; its historical
stim_isg.local_detectors module is only a compatibility re-export. Unit and
public-API behavior belong here, while research-specific Xu-Dua integration
tests remain in auto_detector.
If you use this package in research, please cite:
@software{stim_floquet,
author = {Lu, Bohan},
title = {stim-floquet: Structural SLPC scheduling and detector discovery for CSS codes},
year = {2026},
url = {https://github.com/jerrylvx/stim-floquet}
}MIT