Metadata-Version: 2.4
Name: qiskit-spacetime-bridge
Version: 0.1.0
Summary: Outcome-code and spacetime-code construction for Qiskit Clifford circuits (Delfosse & Paetznick, arXiv:2304.05943)
Author: Rex Rowan
License: Apache-2.0
Project-URL: Homepage, https://github.com/RexRowan/Spacetime-Bridge
Project-URL: Repository, https://github.com/RexRowan/Spacetime-Bridge
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: qiskit<3,>=2.0
Requires-Dist: numpy>=1.22
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Dynamic: license-file

# Qiskit Spacetime Bridge

Outcome-code and spacetime-code construction for Qiskit Clifford circuits,
implementing Algorithm 1 and the back-cumulant construction (Section 5.1)
from Delfosse & Paetznick, "Spacetime codes of Clifford circuits"
(arXiv:2304.05943).

## Install

```
pip install -e .
```

Depends on `qiskit>=2.0,<3` and `numpy`. Confirmed installing and running
correctly from a built wheel in a clean virtualenv (not just from source).

## Usage

```python
from qiskit import QuantumCircuit
from spacetime_bridge import Circuit, analyze

qc = QuantumCircuit(2, 2)
qc.measure(0, 0)
qc.measure(1, 1)
qc.cx(0, 1)
qc.measure(1, 1)   # redundant: forced to equal the XOR of the first two

circuit = Circuit.from_qiskit_circuit(qc)
checks, depth = circuit.finalize()
generators = [circuit.build_spacetime_generator(tag) for (_, tag) in checks]
analyze(generators)
```

Supported instructions: `h`, `s`, `sdg`, `cx`, `measure` (Z-basis, as
standard for Qiskit). Anything else raises `NotImplementedError` rather
than silently mishandling it.

## What's implemented and validated

- `algorithm1.py` — Algorithm 1 (outcome code), augmented stabilizer
  tableau with sign-only phase tracking (justified in-module). 7 tests
  including two specifically stressing sign correctness.
- `spacetime.py` — back-cumulant construction (Section 5.1) turning each
  outcome-code check into a spacetime stabilizer generator. One test case
  independently hand-verified against the paper's closed-form formula
  (Proposition 2), separately from the iterative code.
- `Circuit.from_qiskit_circuit` — real integration with `qiskit.QuantumCircuit`
  (not a standalone reimplementation with a Qiskit-flavored API). Validated
  against a real Qiskit circuit reproducing the hand-verified CNOT case.
- `analysis.py` — symplectic matrix conversion, `[[N,K]]` parameters
  (Theorem 2), pairwise-commutativity sanity check.
- Full test suite re-verified against the actual built wheel installed in a
  clean virtualenv, not just against local source files.

## What's explicitly NOT implemented (honest scope limits)

- **No CZ or SWAP gate rules** — same pattern as H/S/CNOT to add.
- **No Algorithm 3 (LDPC sparsification)** or **logical operators
  (Proposition 10)** — the harder phase-2 work; not started.
- **No code distance or distance bound anywhere** — distance requires
  logical operators; a generator's weight is not a valid stand-in, and
  `analyze()` explicitly does not report one.
- **One level per instruction, not true parallel scheduling** — always
  correct, but produces larger/non-minimal spacetime codes than an
  optimally-scheduled circuit would. Improving this is a performance
  concern, not correctness.
- **`analysis.py` is a generic, package-agnostic implementation** —
  not wired into qiskit-cayley-codes' actual CDZ analysis code (that
  source wasn't available in the session this was built in).
  `to_symplectic_matrix()`'s output is the standard stabilizer-matrix
  format and should drop in directly once that wiring happens.

## Running the tests

```
pip install -e ".[test]"
pytest tests/
```
All currently pass.
