# Q3 Belenos dataset

Raw experimental data and decoding scripts for the Q3 Belenos hardware paper.
This dataset is part of the Supplementary Information: it contains the raw
Quandela/Perceval job exports for every manuscript table row, the decoded
per-port single-photon counts, the backend metadata, and scripts to regenerate
the processed count summaries.

## Contents

- `scripts/decode_quandela_results.py` — decoder for the Quandela/Perceval result
  exports (`:PCVL:zip:` BSCount payloads) → per-port count tables.
- `scripts/photon_number_audit.py` — tallies the photon-number distribution
  (0, 1, 2, ≥3 detected photons) of every export to quantify the directly
  observed multi-photon detection rate.
- `scripts/validate_package.py` — checks required files, decodes the raw exports,
  and verifies that every manifest row has a corresponding raw result file.
- `data/manifest/job_manifest.csv` — maps each manuscript table row to its
  Quandela job and raw result file.
- `data/manifest/job_index.json`, `data/manifest/downloaded_jobs.csv` — sanitized
  dashboard job index and download map.
- `data/manifest/backend_metadata.json` — backend/software metadata queried from
  the live Perceval `RemoteProcessor('qpu:belenos')` API.
- `data/raw/quandela_exports/*.result.json` — raw downloaded Quandela exports for
  every manifest row, plus additional completed Belenos jobs from the same
  campaign.
- `data/raw/quandela_exports/*.payload.json` — matching payload/job-detail
  exports.
- `data/processed/per_port_counts.csv`, `data/processed/job_summary.csv` —
  decoded per-port counts and per-job summaries (regenerated by the decoder).
- `data/processed/reported_table_values.csv` — the values reported in the
  manuscript, for cross-checking.

## Backend / software metadata

From `data/manifest/backend_metadata.json` (queried from the live Perceval
`RemoteProcessor('qpu:belenos')` API with Perceval 1.0.1; no access token is
included):

- backend: `qpu:belenos` ("Belenos QPU")
- Perceval client: 1.0.1
- backend software: `mosaiq-belenos 2.7.12`, `hardware-core 3.7.4`,
  `pcvl-worker 1.4.0`, `perceval-quandela 1.1.0`, `universalchipworker 1.7.0`,
  `exqalibur 1.1.1`
- remote-processor performance metadata: `Clock 4.94 MHz`, `HOM 91.0%`,
  `Transmittance 4.84%`, `g2 1.9%`

## Verified export

The `E4f_control_no` export decodes to:

- all detected events: 10,000
- single-photon postselected events: 9,996
- port-0 dump count: 1,956
- dump probability: 0.1957
- Wilson 95% CI: [0.1880, 0.2036]

This is the sixth Experiment 4 configuration that accounts for the 60,000-event
total in the manuscript.

## Photon-number audit (multi-photon contamination)

`scripts/photon_number_audit.py` decodes every export and tallies detected
photon number, for both the manuscript six-experiment job set (taken from the
unique `raw_result_file` entries of `job_manifest.csv`) and the full archive.
Across the 350,000 events of the six experiments, 171 registered two photons
and none registered three or more — a directly observed multi-photon detection
fraction of 0.049% (≤ 0.10%, i.e. ≤ 10/10,000, in any single configuration);
the same 0.049% rate holds over the full 690,000-event archive (341 two-photon
events). These detected pairs are removed by the single-photon postselection.
Lost-twin survivors (two-photon emission, one photon lost) sit at ≈ 1.9% of the
single-photon counts given the 4.84% transmittance, but a lone survivor
reproduces the intended single-particle port distribution and so does not bias
the measured fractions. See the *Multi-photon contamination* paragraph in the
manuscript Methods.

## Rebuild the decoded tables

From this directory:

```sh
python3 scripts/decode_quandela_results.py
```

Outputs `data/processed/per_port_counts.csv` and `data/processed/job_summary.csv`.

To validate the dataset:

```sh
python3 scripts/validate_package.py
```

## Reproducing the paper from this dataset

The analysis pipeline in `../analysis/` consumes this dataset directly:

```sh
cd ../analysis
python3 verify_package.py      # recomputes every table row from these counts
python3 build_raw_counts.py    # writes data/raw_port_counts.csv from this dataset
python3 reproduce_all.py       # tables + benchmarks + figures
```
