Initial public release

Author: UlysseChabaud

.github/workflows/tests.yml

@@ -0,0 +1,27 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install package
+        run: python -m pip install --upgrade pip && python -m pip install -e .
+      - name: Run tests
+        run: python -m unittest discover -s tests -v

.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Editors and operating systems
+.DS_Store
+.idea/
+.vscode/
+
+# Local agent configuration
+.agents/
+.codex/
+
+# Generated simulation and report artifacts
+/output/
+/tmp/
+
+# Local reference papers; cite or link to their public sources instead
+/2411.04688v1.pdf
+/Boson_Sampling_with_characteristic_function.pdf

CITATION.cff

@@ -0,0 +1,12 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it using the metadata below."
+title: "Bosonic verification simulator"
+type: software
+authors:
+  - family-names: "Chabaud"
+    given-names: "Ulysse"
+version: 0.1.0
+date-released: 2026-08-10
+repository-code: "https://github.com/UlysseChabaud/bosonic-verification"
+url: "https://github.com/UlysseChabaud/bosonic-verification"
+license: MIT

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ulysse Chabaud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,131 @@
+# Bosonic verification simulator
+
+`cv-verification` is a NumPy-based simulator for fidelity-witness protocols
+in four-mode bosonic experiments. It models finite-support pure input states,
+a passive interferometer, binary characteristic-function measurements,
+readout-error mitigation, and finite-sample witness estimation.
+
+The implemented protocols are:
+
+- `single_mode`: \(W^{(1)}=\sum_i F_i-3\);
+- `disjoint_two_mode`: \(F_{ij}+F_{kl}-1\) for a fixed pairing;
+- `max_two_mode`: the maximum of 16 intersection-corrected spanning-tree
+  witnesses.
+
+## Installation
+
+Python 3.11 or later is required.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e .
+```
+
+## Run one experiment
+
+```bash
+python -m cv_verification examples/fock_hadamard.json \
+  --output output/runs/fock_hadamard
+```
+
+Equivalently, after installation:
+
+```bash
+cv-verify examples/fock_hadamard.json \
+  --output output/runs/fock_hadamard
+```
+
+Each run writes a machine-readable summary, resolved configuration,
+per-trial data, and comparison plots. Generated files are placed under
+`output/`, which is excluded from version control.
+
+Ideal single-mode inputs may be specified as number states, normalized finite
+Fock vectors, or the included finite GKP-core preset. Complex coefficients and
+unitary entries accept real numbers, Python-style complex strings, `[real,
+imag]`, or `{\"real\": ..., \"imag\": ...}`.
+
+## Reproduce the Fock-input scaling study
+
+```bash
+python scripts/run_hadamard_demo.py \
+  --output output/demo/hadamard \
+  --repetitions 5000
+```
+
+This studies \({|1\rangle}^{\otimes4}\) followed by the normalized
+Sylvester-Hadamard interferometer, using sample counts from \(1\) to \(10^7\).
+The preparation, interferometer, and measurement fidelities may be changed
+with the corresponding command-line options.
+
+The \(0.5\)-target threshold and selected \(0.9/0.9\) operating point are
+reproduced with:
+
+```bash
+python scripts/find_hadamard_thresholds.py \
+  --output output/demo/hadamard_high_fidelity
+
+python scripts/run_hadamard_demo.py \
+  --output output/demo/hadamard_high_fidelity \
+  --repetitions 5000 \
+  --preparation-fidelity 0.9 \
+  --interferometer-fidelity 0.9 \
+  --measurement-fidelity 1.0
+```
+
+## Reproduce the truncated-GKP study
+
+The finite GKP preset is the normalized projection of the finite-energy
+square-GKP \(|0\rangle\) ansatz onto Fock levels \(0,\ldots,6\), with
+\(\Delta=0.5\). Run the baseline, selected operating point, sample-count
+sweeps, and balanced-threshold search with:
+
+```bash
+python scripts/run_gkp_hadamard_analysis.py \
+  --output-root output/demo \
+  --delta 0.5 \
+  --cutoff 6 \
+  --repetitions 5000
+```
+
+The exact four-mode GKP evolution is computationally heavier than the Fock
+example; the script reuses each exact state across all sample counts.
+
+## Statistical and physical conventions
+
+- States and shots are independent and identically distributed.
+- Preparation and interferometer imperfections remain fixed within a sweep;
+  repeated trials vary only shot noise.
+- The interferometer is passive and photon-number conserving.
+- All ideal inputs have finite Fock support.
+- Scalar device fidelities select a canonical seeded pure-error model; they do
+  not uniquely specify an experimental noise channel.
+- Measurement fidelity is the assignment fidelity of one joint binary
+  characteristic-function readout. It is neither a product of four per-mode
+  detector fidelities nor a global state fidelity.
+- Known symmetric assignment errors are mitigated using visibility
+  \(v=2f_{\mathrm{meas}}-1\). Mitigation removes asymptotic bias and increases
+  statistical uncertainty by \(1/v\).
+- Hoeffding bounds are distribution-free and include the 16-candidate union
+  bound for `max_two_mode`.
+
+## Tests
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+The test suite covers Fock evolution, marginal fidelities, interferometer
+calibration, characteristic-function identities and norms, all witness
+formulas, readout mitigation, Hoeffding coverage, reproducibility, and output
+schemas.
+
+## Citation
+
+Please use the metadata in [`CITATION.cff`](CITATION.cff). A versioned Zenodo
+DOI can be added after the first GitHub release.
+
+## License
+
+This project is released under the [MIT License](LICENSE).

cv_verification/__init__.py

@@ -0,0 +1,6 @@
+"""Four-mode characteristic-function fidelity-witness simulation."""
+
+from .config import SimulationConfig
+from .simulation import SimulationResult, run_simulation
+
+__all__ = ["SimulationConfig", "SimulationResult", "run_simulation"]

cv_verification/__main__.py

@@ -0,0 +1,56 @@
+"""Command-line interface for cv_verification."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from .config import SimulationConfig
+from .reporting import write_simulation_result
+from .simulation import run_simulation
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="cv-verify",
+        description=(
+            "Simulate four-mode characteristic-function fidelity witnesses"
+        ),
+    )
+    parser.add_argument("config", type=Path, help="JSON simulation configuration")
+    parser.add_argument(
+        "--output",
+        type=Path,
+        required=True,
+        help="directory for JSON, CSV, and PNG outputs",
+    )
+    return parser
+
+
+def main() -> None:
+    args = build_parser().parse_args()
+    config = SimulationConfig.from_json(args.config)
+    result = run_simulation(config)
+    output = write_simulation_result(result, args.output)
+    print(
+        json.dumps(
+            {
+                "output": str(output.resolve()),
+                "witness_type": result.summary["witness_type"],
+                "estimated_witness": result.summary[
+                    "one_run_mitigated_witness"
+                ],
+                "exact_witness": result.summary["exact_selected_witness"],
+                "true_fidelity": result.summary["true_global_fidelity"],
+                "empirical_precision": result.summary["empirical_precision"],
+                "hoeffding_precision": result.summary["hoeffding_precision"],
+            },
+            indent=2,
+            sort_keys=True,
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()