# Quantum protocol and component benchmarks

Open the Research Workbench with the existing desktop launcher and choose
**Quantum benchmarks**. Select all profiles or one of the nine component/protocol
presets, edit its complete configuration, validate it, and run. The Results view
contains calculated curves, tables and the separate narrative report. No command
line is required. The exact workflow label and steps are in `GUI_GUIDE.md`.

The models in this workflow are controlled component/protocol benchmarks. They
do not implicitly import a satellite scenario, apply a PF boost, or replace the
mission simulation's channel. Use the existing simulation and comparison
workflows for orbital histories, SR/GR photon timing and mission-level QKD.
In r20, those mission workflows also expose explicit **Quantum experiments**;
see `MISSION_QUANTUM_GUIDE.md`. A standalone run remains independent unless the
mission experiment interface is selected.

## Command equivalents

```bat
run_quantum_benchmarks_python38.bat --profile all --config config_quantum_benchmarks.json --output results_quantum
run_quantum_benchmarks_python38.bat --profile hom --config config_quantum_hom.json --output results_hom
```

Cross-platform: `python run_quantum_benchmarks.py` with the same options.
Use a fresh output directory for each run. `--no-plots` skips standalone figure
files but retains the narrative PDF, numerical data and plotted report pages.
`--write-default-config my_config.json` exports defaults without running.

## Model profiles

| Profile | Executed calculation | Main outputs |
|---|---|---|
| `bell` | Two-qubit density matrix and measurement Born probabilities | Fidelity, purity, negativity, chosen-settings and optimized CHSH |
| `teleportation` | Three-qubit Bell measurement and outcome-dependent corrections | Conditional output states, six-state average fidelity, branch success |
| `swapping` | Four-qubit Bell measurement and endpoint correction | Conditional entanglement and heralding probability |
| `purification` | Bilateral recurrence operations, accepted branches and optional twirl | Output quality, success, yield and input-pair cost |
| `memory` | Local T1/T2 Kraus maps and separate retrieval erasure | Density matrices, coherence, fidelity/purity and retrieval probability |
| `repeater` | Seeded link attempts, cutoff/restart events, memory evolution and actual swap operations | Delivery rate, sampling uncertainty, waits, consumed attempts and conditional quality |
| `hom` | Normalized Gaussian wavepacket overlap and independent quadrature | Coincidence probabilities and detected coincidence rate |
| `qkd_sweep` | Declared Poisson/threshold optical counts through both existing security engines | QBER, finite/asymptotic key forecasts and mode-normalized PLOB reference |
| `channel_tomography` | Qiskit channel evolution on informationally complete probes | PTM, Choi, process/average fidelity and optional simulated measurement counts |

The full mathematical assumptions and every setting are documented in manual
Chapter 25. Defaults illustrate model behavior; they are not calibrated device
parameters or mandatory industry settings.

## Reading the evidence

`quantum_benchmark_suite.json` combines all selected profile reports. Individual
profile JSON files contain the same final result objects. `*_series.csv` exports
the full computed series (nested quantities remain JSON strings in CSV cells).
`resolved_config.json` preserves inputs. `quantum_benchmark_report.pdf` contains
narrative interpretation, assumptions, metrics, numerical checks and figures.
The same-stem files in `figures/` are PNG previews and vector PDF versions of the
same graph. They do not contain additional narrative.

`quantum_benchmark_manifest.json` records Python/dependency versions, source
hashes, configuration and artifact hashes. Hashes establish content identity,
not physical truth or an authenticated laboratory measurement.

Run the optional read-only check without modifying the saved run:

```text
python validate_quantum_benchmarks.py results_quantum
python validate_quantum_benchmarks.py results_quantum --check-current-source
```

The second form additionally tests whether the current installation has the
same source bytes as the run. A later intentional software revision can differ
while the original saved artifacts remain intact.

Bell sampling records the signed CHSH sum and its magnitude separately.
`signed_chsh_sampling_standard_deviation` describes the signed estimator from
independent shots per setting. It is not the exact uncertainty of the absolute
value near zero or a Bell-violation confidence statement.

## Targets and failure interpretation

Each report separates numerical PASS/FAIL, engineering criteria and empirical
validation. The new workflow has no experimental observations, so empirical
validation remains NOT_ASSESSED. Existing published-data workflows retain their
own evidence categories.

You can add predeclared targets in the top-level `requirements` array. For example:

```json
{
  "id": "minimum-memory-fidelity",
  "profile": "memory",
  "metric": "conditional_fidelity",
  "aggregation": "minimum",
  "operator": ">=",
  "value": 0.9
}
```

The metric names are exact scalar series fields. Aggregation can be `minimum`,
`maximum` or `mean`; the operator is `>=` or `<=`. Every selected row counts.
Unavailable values produce NOT_ASSESSED, with no silent dropping of failed
events. Unknown metric names are input errors. No targets are enabled by default.

With `--require-engineering-pass`, a failed or unavailable configured target,
or an empty requirements list, returns exit status 3 after preserving results.
The suite reports engineering status separately as PASS, FAIL or NOT_ASSESSED;
no requirements and unavailable metrics remain NOT_ASSESSED. Numerical failure returns 2.
Ordinary completion returns 0 even though empirical validation is unassessed.
Input/parser errors are also nonzero; inspect the explicit diagnostic.

A valid zero key, no delivered pair, nonviolating CHSH value or fidelity below a
design target is not automatically a broken model. Investigate the recorded
cause and test a defensible apparatus/operating change in a new run. Do not
relax security, edit reference data or redefine the requirement to manufacture
a PASS. Recommendations do not guarantee performance.

## Scope of comparison

`COMPETITIVE_BENCHMARK_SOURCES.md` and
`benchmark_data/competitive/sources.json` map public industry capabilities to
published references. These are independent implementations. General network
routing, network-scale resource contention, hardware orchestration, device-
specific calibration and advanced QKD families are not implied by elementary
protocol coverage. There is no vendor runtime superiority, full feature parity
or standards certification claim.

## Complete-state protocol interface (r20)

The legacy standalone fidelity sweeps retain their declared depolarized-resource
assumptions. The mission interface uses a different, explicit state API:

```python
from pf_benchmarks.protocols import run_state_protocol
result = run_state_protocol(name, rho, config=None, second_state=None)
```

`rho` accepts a complex 4 x 4 matrix or a JSON object with `real`, `imag`,
`basis_order` and `num_qubits`. The basis is Qiskit little endian, `|q1 q0>`;
`q0` is Alice and `q1` is Bob. `second_state` is mandatory for swapping and
purification; tensoring the pairs declares their independence. The API validates
states without silently repairing, normalizing, twirling or fitting them from
fidelity. Purification twirling is available only as an explicit operation.

The API executes Bell, teleportation, swapping or one-round purification on the
provided matrices. Its success probability is conditional on the input resources
being available; the mission layer accounts for physical availability separately.
A teleportation `input_density_matrix` can specify an input qubit, otherwise the
runner evaluates the six Pauli probe states. Partial Bell measurements can have
input-dependent acceptance, so the heralding convention accompanies fidelity.
The result retains actual input/output matrices and records
`state_reconstruction_from_fidelity: false` in its provenance.

Do not pass `fidelity_values` or `link_b_fidelity` into this full-state API. Those
belong to the standalone source-model sweeps, not to received mission states.