Reproducibility¶
The main pipeline's numbers, figures, and tables are regenerated from a fixed seed by one command,
scripts/reproduce_all.py. The kernel bandwidth ablation and its post-hoc control are rebuilt by two
more, scripts/ablate_kernel_bandwidth.py and then scripts/posthoc_tuned_rbf_control.py (see
below).
Environment¶
- Python 3.10 to 3.12. On Windows, use the launcher:
py -3.11. - Verified stack: Qiskit 1.4.5, qiskit-machine-learning 0.8.4, scikit-learn 1.8, pandas 3.0, numpy 2.4.
- Also rerun on Linux with Qiskit 1.4.6, qiskit-machine-learning 0.8.4, scikit-learn 1.9.1, pandas 3.0.6, numpy 2.4.6: the classical and QSVM metrics matched exactly on Python 3.11, and the seeded VQC and QNN gave identical metrics on Python 3.11 and 3.12.
Install the package with its development tools:
Reproduce everything¶
This runs all five pipeline stages (data, classical baseline, QSVM, VQC and QNN, reports) and then refreshes the README results table. Override the defaults when you want a quicker or larger run:
| Flag | Default | Meaning |
|---|---|---|
--n |
200 | quantum training subsample (the kernel is O(N squared)) |
--k |
6 | features selected for the quantum encoding (qubits) |
--reps |
2 | feature-map and ansatz repetitions |
--maxiter |
60 | COBYLA iterations for the VQC and QNN |
Individual stages are also available as scripts: scripts/download_data.py,
scripts/train_baseline.py, scripts/train_qsvm.py, and scripts/train_vqc_qnn.py.
The kernel bandwidth ablation runs separately, reads the committed reports/results.json without
changing it, and writes reports/bandwidth_ablation.json and its figure:
The second command is the post-hoc tuned RBF control. It adds the key posthoc_tuned_rbf to
reports/bandwidth_ablation.json; the ablation script rewrites that file without it, so run the
control after the ablation. The JSON's prespecified key keeps its name for compatibility: it holds
the design fixed before the script's first run, which was not blind to test results (see the
script's docstring).
Determinism and the data caveat¶
All randomness is seeded with RANDOM_SEED = 42: the splits, the model fits (including the VQC and
QNN initial weights and shot sampling), and the bootstrap resampling. Re-running the pipeline
reproduces the same metrics; only the wall-clock training times change. Re-running also rewrites the
committed figures in reports/figures/. On another machine the fonts may render differently, but the
plotted values are the same, apart from the training times in runtime_comparison.png.
Without Kaggle credentials the pipeline uses the synthetic fallback, so the numbers shown on this site
come from synthetic data. They are internally consistent and reproducible, but they are not the real
WiDS results. To run on the real data, place a Kaggle API token at ~/.kaggle/kaggle.json, delete
the synthetic fallback at data/raw/training_v2.csv (otherwise it is reused), and re-run.
Rebuild this site¶
py -3.11 -m pip install -e ".[docs]"
py -3.11 scripts/sync_docs_assets.py # tables + chart data + demo model + figures
py -3.11 -m mkdocs serve # preview at http://127.0.0.1:8000/
py -3.11 -m mkdocs build --strict # production build into site/
scripts/sync_docs_assets.py regenerates the results table, the chart data, and the demo model, then
copies the figures into the site. The deploy workflow runs the same steps in CI.
Tests¶
The suite is deterministic and offline (it uses the synthetic generator), and it includes a check that the exported demo model's JavaScript math matches scikit-learn, and that the docs tables carry no fabricated numbers.