# Q3 paper — analysis scripts

Python analysis pipeline for *"Characterization of nested Walsh parity-check
filters in a single-photon eight-mode register on a cloud photonic processor"*.
It regenerates the
construction's operator algebra, the six hardware tables, the simulation
benchmarks (Table I), and the data-bearing figures from the measured counts.

> **Provenance.** The pipeline runs on the measured per-output-port
> single-photon counts in the experimental dataset (`../dataset/`).
> `data/raw_port_counts.csv` is populated from the decoded Quandela exports by
> `build_raw_counts.py`, and those per-port counts drive every result. The
> embedded `hardware_data.py` constants and `data/hardware_counts.csv` are a
> summary-level fallback (and back the Exp. 5B selectivity rows). The hardware
> tables, the Exp. 1 per-mode breakdown, and every headline number reproduce
> directly from the data — see `verify_package.py`.

## Layout

| File | Purpose |
|------|---------|
| `stats.py` | Estimators: Wilson CI, log-ratio (delta) suppression ratio, Fisher-z Pearson CI, the `p_floor + g·c²/(1+c²)` calibration fit. |
| `operators.py` | Operator algebra on C⁸: BALANCE `B`, FOLD `F`, BRAID `G₁,G₂,G₃`, dynamics `R` and core `R_N`, check matrix `C`, code/character bases, QR state preparation, and distance checks `d(N)=2`, `d(S)=4`. |
| `data_io.py` | CSV-backed loader. Resolves counts from `data/raw_port_counts.csv` (per-port), then `data/hardware_counts.csv` (summary), then the embedded fallback. Import as `import data_io as hw`. |
| `hardware_data.py` | Summary-level fallback counts for Experiments 1–6 and the Perceval device metadata for `qpu:belenos`. |
| `data/hardware_counts.csv` | Summary `(x, n)` table (fallback). |
| `data/raw_port_counts.csv` | Per-port counts (`n0..n7`) for each configuration, built from the dataset; these drive the results. |
| `reproduce_tables.py` | Recomputes Tables II–VII and the Fig. 3 data series, printed next to the paper's values. |
| `simulations.py` | Simulation benchmarks B1–B8; B3 and B5 are retained as legacy archived benchmarks only and are not reported in the manuscript. |
| `figures.py` | Regenerates Fig. 3 (`fig_exp4_core_depth`) and the Experiment 2 three-tier bar chart (`fig_exp2_three_tier`). |
| `build_raw_counts.py` | Fills `data/raw_port_counts.csv` from the dataset (`../dataset/`) via the job manifest. Re-run if the dataset changes. |
| `verify_package.py` | Recomputes every table row + headline suppression ratio straight from the dataset's decoded per-port counts and prints them next to the paper. |
| `extract_core.py` | Decodes the compiled Experiment 4 interferometers from the archived payloads and characterizes the implemented neutral-sector core `R_N = S†U₁U₀†S` **as executed** (real, orthogonal; fixes the DC/uniform direction with eigenvalue +1; `det = -1`). Reproduces the manuscript's Table I validation checks and writes the core operator, eigenphases, and per-depth interferometers `U_d` to `data/executed_core/`. |
| `reproduce_all.py` | Runs everything. |

## Experimental dataset

The measured data lives in `../dataset/` (raw Quandela `payload`/`result` JSON
exports, decoded `per_port_counts.csv`, `job_manifest.csv` mapping each
manuscript row to its job, and `backend_metadata.json`). Two entry points use it:

```bash
python verify_package.py        # paper vs data, row by row
python build_raw_counts.py      # refresh data/raw_port_counts.csv from the dataset
```

`backend_metadata.json` confirms the Methods values: `qpu:belenos`, Perceval
client `1.0.1`, the full backend software stack, and `Clock 4.94 MHz`,
`HOM 91.0%`, `transmittance 4.84%`, `g2 1.9%`.

## Per-port data format

`data/raw_port_counts.csv` holds one row per configuration with eight columns
`n0..n7` of postselected single-photon counts per output port. The loader
computes, for each row:

- `n` = sum of the eight port counts (total postselected single-photon events);
- `x` per the row's `metric`: `dump` → port 0; `syndrome_sum` → ports 0+1+2+3
  (Exp. 5A/5C); `port` → `ports[target_port]` (Exp. 5B selectivity);
- code-side fidelity (Exp. 5A) = `ports[target_port] / n`.

Any row whose `n0..n7` are filled overrides the summary CSV automatically. Rows
left blank fall back to the summary counts. To regenerate the CSV templates from
the embedded values, run `python data_io.py`; to fill them from the dataset, run
`python build_raw_counts.py`.

## Usage

```bash
pip install -r requirements.txt
python reproduce_all.py        # tables + benchmarks + figures
# or individually:
python reproduce_tables.py
python simulations.py
python figures.py
```

## What matches the paper

Recomputed from the measured counts, these reproduce the manuscript (rounding
aside):

- Exp. 1 BALANCE separator: mean dump **0.188**, std **0.030**, best **0.140**
  (from the per-mode `RS_BALANCE_mode0..7` exports)
- Neutral suppression **31.6×** and pooled neutral leakage **0.6%** (Exp. 2)
- Error-injection calibration fit **p_floor = 0.010, g = 1.12** and Pearson
  **r = 0.9992** (Exp. 3)
- Experiment 4 dump probabilities and the Fig. 3 error bars
- Syndrome suppression **23.7×**, mean syndrome leakage **2.32%**, mean code
  fidelity **95.1%** (Exp. 5)
- HOM control dump probabilities across the three chip states (Exp. 6)

Simulation benchmarks split into three groups:

- **Exact** (determined by the construction): B1 (`rank B = 7`,
  `‖B²−B‖ = 0`), B2 (`rank 7`, mean overlap `1/7`), B6 (`κ = 1.000000` at 200
  cycles), B7a (single-mode decoder `100%`). These match to numerical precision.
- **Model-dependent manuscript checks**: B4 BALANCE cadence, B7b weight-2
  greedy decoder, B8 parity-vs-BALANCE. The transparent dephasing model in
  `simulations.py` reproduces the qualitative outcomes (e.g. B8 wins 16/16);
  absolute percentages for B4/B7b are model-sensitive and are flagged inline.
- **Legacy archived only**: B3 throughput and B5 J-cost are retained in
  `simulations.py` for completeness from earlier drafts, but they are not
  reported in the manuscript and are not listed as paper matches.

## Notes

- A fixed RNG seed (`SEED` in `simulations.py`) makes the stochastic benchmarks
  reproducible.
- `operators.py` builds the **design** core from the nominal FOLD/BRAID
  parameters (`θ = π/4`, `ψ = 2π/3`, triads `T₁={0,1,3}`, `T₂={2,6,7}`,
  `T₃={0,4,5}`). The core that was actually **compiled and executed** in
  Experiment 4, recovered by `extract_core.py` from the archived payloads, is a
  *real-orthogonal* operator that fixes the uniform vector with eigenvalue `+1`
  (so it preserves `N`). It is **not** the design instance: `neutral_core()` is
  complex and assigns the uniform vector eigenvalue `i = e^{iπ/2}`, and the two
  spectra differ. Both fix the uniform vector — the only property the paper's
  results use — and Table I of the manuscript reports the validation checks for
  the executed operator, regenerated from the archived payloads by
  `extract_core.py`.
