Update README.md

60ab275 verified 3 months ago

8.04 kB

# The Edges That Vanish — Reproducibility Package

Code, raw results and figures accompanying the paper:

> **The Edges That Vanish: A Reproducible Assessment of Amplitude Permutation,
> Circuit Cost and Metric Choice in Quantum Hadamard Edge Detection**

Every number, table and figure in the paper is produced by the single notebook in
this repository. No result is hand-edited.

---

## What this study does

Quantum Hadamard Edge Detection (QHED) encodes an image into the amplitudes of a
quantum state and extracts edges with a small number of gates. The construction
most often used in the literature applies the Hadamard gate directly to the least
significant qubit of the data register — and, in doing so, structurally discards
half of the neighbouring pixel pairs.

This repository implements both constructions, compares them against four classical
operators under a single evaluation protocol, and measures the end-to-end circuit
cost, the device-noise sensitivity and the measurement budget that quantum edge
detection actually requires.

| Finding | Value |
|---|---|
| Improvement from the amplitude-permutation correction (ODS-F1) | 0.480 → 0.798 (+66.3%) |
| Share of two-qubit gate cost from state preparation (N = 1024) | 59.0% |
| Error rate at which edge quality drops more than 15% | p₂ = 0.001 |
| Shots per scan line for near-saturation quality | ≈ 16 384 |

---

## Quick start

### Google Colab (recommended)

Upload `QHED_Comparative_Study.ipynb` and choose **Runtime → Run all**.
No GPU is required. Expected runtime is **18–22 minutes** on a standard CPU runtime.

### Local

```bash
python -m venv .venv && source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -r requirements.txt
jupyter lab QHED_Comparative_Study.ipynb             # then run all cells
```

The final cell writes every artefact to `results/` and packages it as
`qhed_results.zip`.

---

## Repository layout

```
.
├── QHED_Comparative_Study.ipynb   single notebook — produces everything
├── requirements.txt               pinned dependency versions
├── LICENSE                        MIT
├── CITATION.cff                   citation metadata
└── results/
    ├── figures/                   14 figures (13 from the notebook + the pipeline diagram)
    ├── csv/                       13 machine-readable result tables  ← filled by the notebook
    ├── latex/                     9 tables as \input-ready LaTeX      ← filled by the notebook
    ├── environment.json           interpreter and library fingerprint ← written by the notebook
    ├── findings_summary.txt       auto-filled numeric summary          ← written by the notebook
    └── paper_outline.txt          section plan and limitations         ← written by the notebook
```

The final notebook cell writes every table and text artefact into `results/` and
packages the folder as `qhed_results.zip`. See `results/README.md`.

---

## Mapping from paper to artefacts

| Paper | Artefact |
|---|---|
| Table I — edge detection quality | `csv/table1_quality.csv` |
| Table II — tolerance sensitivity | `csv/table2a_tolerance.csv` |
| Table III — resolution sensitivity | `csv/table2b_resolution.csv` |
| Table IV — noise robustness | `csv/table3_noise_FoM.csv` |
| Table V — circuit cost scaling | `csv/table4_scaling.csv` |
| Table VI — device noise | `csv/table5_device_noise.csv` |
| Table VII — measurement budget | `csv/table6_shots.csv` |
| Table VIII — ranking stability | `csv/table8_rank_stability.csv` |
| Table IX — targeted hypotheses | `csv/table9_hypotheses.csv` |
| Figures 2–12 | `figures/` |

Figure 1 (the pipeline diagram) is drawn separately and is not produced by the
notebook.

---

## Reproducibility

**Determinism.** All randomness is seeded. The global seed is `42`. Noise
realisations are seeded per (image, noise type, level) triple.

> **A note on seeding.** An earlier version of this code derived those per-condition
> seeds from Python's built-in `hash()`. Python salts string hashing differently in
> every interpreter process (see `PYTHONHASHSEED`), so those "seeded" noise
> realisations were in fact different on every run. The current version uses
> `zlib.crc32`, which is stable across processes, platforms and Python versions.
> If you are adapting this code, do not seed from `hash()` on strings.

**Verification built into the notebook.** Before any experiment runs, a unit-test
cell compares the circuit output against the analytic neighbour gradient
|f_i − f_{i+1}|. The largest absolute deviation over N = 8 … 64 is on the order of
10⁻¹⁴, at the limit of double-precision arithmetic. If this assertion fails, the
notebook stops.

**Environment.** The reference run used:

| Component | Version |
|---|---|
| Python | 3.12.3 |
| Qiskit | 2.5.1 |
| Qiskit Aer | 0.17.2 |
| NumPy | 2.4.4 |
| scikit-image | 0.26.0 |
| OpenCV | 4.13.0 |

The notebook re-prints this fingerprint at run time and writes it to
`results/environment.json`.

**Expected drift.** Quality metrics (Tables I–IV, VI–IX) should reproduce exactly.
Circuit depth and gate counts (Table V) depend on the Qiskit transpiler and may
shift by a few percent under a different Qiskit minor version; the qualitative
conclusion — that state preparation dominates the two-qubit gate cost — is not
affected.

---

## Method in brief

1. **Dataset** — eight synthetic shapes plus a binary silhouette, generated
   *directly at the target resolution*. Ground-truth edges come from a
   morphological boundary of the binary mask.

   Down-sampling a larger image is deliberately avoided: it fragments the
   one-pixel-wide ground-truth map and deletes roughly 54% of its edge pixels,
   which artificially rewards detectors producing fragmented output. The notebook
   prints this loss figure as a diagnostic.

2. **Encoding** — QPIE amplitude encoding, c = f / ‖f‖, on n = log₂N qubits.

3. **Circuit** — full-boundary QHED on n + 1 qubits:
   H(q₀) → D₍₂^(n+1)₎ → H(q₀), where D is a decrement (amplitude-permutation) gate
   built from a chain of multi-controlled X gates. Odd-index amplitudes carry the
   neighbour gradient.

4. **Evaluation** — Pratt Figure of Merit as the primary metric; F1 at a matching
   tolerance of ρ = 1 px as secondary, with the tolerance derived from the BSDS
   scaling rule (0.0075 × image diagonal). Threshold sweep over 33 levels
   (ODS and OIS protocols).

5. **Statistics** — Friedman test with Nemenyi critical difference, pairwise
   Wilcoxon tests with Holm correction, and five pre-specified hypotheses reported
   with rank-biserial effect sizes.

---

## Runtime breakdown

| Stage | Approx. time |
|---|---|
| Setup, unit tests, circuit diagrams | 1 min |
| Experiment 1 — edge quality (64 × 64) | 1 min |
| Experiment 2 — tolerance and resolution sweeps | 3 min |
| Experiment 3 — noise robustness (32 × 32) | 5 min |
| Experiment 4 — circuit cost scaling | < 1 min |
| Experiment 5 — device noise and shot budget | 3 min |
| Statistics, export, packaging | 1 min |

The resolution sweep at S = 128 is the single most expensive step. Reduce
`RES_GRID` if you want a faster pass.

---

## Limitations

- Ground-truth edges are derived from synthetic and silhouette images. No
  human-annotated benchmark (e.g. BSDS500) was used.
- Experiments run on classical simulation only; no real quantum hardware.
- The device-noise model assumes uniform depolarisation. Qubit-specific relaxation,
  read-out error and cross-talk are not modelled, and state preparation is treated
  as ideal — so the reported degradation is a lower bound.
- The `QHED-full+S` variant applies a classical smoothing post-process and is
  therefore a hybrid pipeline, not a fully quantum algorithm.

---

## Citation

If you use this code, please cite both the paper and this archive. See
`CITATION.cff` for machine-readable metadata.

---

## License

MIT — see `LICENSE`.

	# The Edges That Vanish — Reproducibility Package

	Code, raw results and figures accompanying the paper:

	> **The Edges That Vanish: A Reproducible Assessment of Amplitude Permutation,
	> Circuit Cost and Metric Choice in Quantum Hadamard Edge Detection**

	Every number, table and figure in the paper is produced by the single notebook in
	this repository. No result is hand-edited.

	---

	## What this study does

	Quantum Hadamard Edge Detection (QHED) encodes an image into the amplitudes of a
	quantum state and extracts edges with a small number of gates. The construction
	most often used in the literature applies the Hadamard gate directly to the least
	significant qubit of the data register — and, in doing so, structurally discards
	half of the neighbouring pixel pairs.

	This repository implements both constructions, compares them against four classical
	operators under a single evaluation protocol, and measures the end-to-end circuit
	cost, the device-noise sensitivity and the measurement budget that quantum edge
	detection actually requires.

	\| Finding \| Value \|
	\|---\|---\|
	\| Improvement from the amplitude-permutation correction (ODS-F1) \| 0.480 → 0.798 (+66.3%) \|
	\| Share of two-qubit gate cost from state preparation (N = 1024) \| 59.0% \|
	\| Error rate at which edge quality drops more than 15% \| p₂ = 0.001 \|
	\| Shots per scan line for near-saturation quality \| ≈ 16 384 \|

	---

	## Quick start

	### Google Colab (recommended)

	Upload `QHED_Comparative_Study.ipynb` and choose Runtime → Run all.
	No GPU is required. Expected runtime is 18–22 minutes on a standard CPU runtime.

	### Local

	```bash
	python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
	pip install -r requirements.txt
	jupyter lab QHED_Comparative_Study.ipynb # then run all cells
	```

	The final cell writes every artefact to `results/` and packages it as
	`qhed_results.zip`.

	---

	## Repository layout

	```
	.
	├── QHED_Comparative_Study.ipynb single notebook — produces everything
	├── requirements.txt pinned dependency versions
	├── LICENSE MIT
	├── CITATION.cff citation metadata
	└── results/
	├── figures/ 14 figures (13 from the notebook + the pipeline diagram)
	├── csv/ 13 machine-readable result tables ← filled by the notebook
	├── latex/ 9 tables as \input-ready LaTeX ← filled by the notebook
	├── environment.json interpreter and library fingerprint ← written by the notebook
	├── findings_summary.txt auto-filled numeric summary ← written by the notebook
	└── paper_outline.txt section plan and limitations ← written by the notebook
	```

	The final notebook cell writes every table and text artefact into `results/` and
	packages the folder as `qhed_results.zip`. See `results/README.md`.

	---

	## Mapping from paper to artefacts

	\| Paper \| Artefact \|
	\|---\|---\|
	\| Table I — edge detection quality \| `csv/table1_quality.csv` \|
	\| Table II — tolerance sensitivity \| `csv/table2a_tolerance.csv` \|
	\| Table III — resolution sensitivity \| `csv/table2b_resolution.csv` \|
	\| Table IV — noise robustness \| `csv/table3_noise_FoM.csv` \|
	\| Table V — circuit cost scaling \| `csv/table4_scaling.csv` \|
	\| Table VI — device noise \| `csv/table5_device_noise.csv` \|
	\| Table VII — measurement budget \| `csv/table6_shots.csv` \|
	\| Table VIII — ranking stability \| `csv/table8_rank_stability.csv` \|
	\| Table IX — targeted hypotheses \| `csv/table9_hypotheses.csv` \|
	\| Figures 2–12 \| `figures/` \|

	Figure 1 (the pipeline diagram) is drawn separately and is not produced by the
	notebook.

	---

	## Reproducibility

	Determinism. All randomness is seeded. The global seed is `42`. Noise
	realisations are seeded per (image, noise type, level) triple.

	> A note on seeding. An earlier version of this code derived those per-condition
	> seeds from Python's built-in `hash()`. Python salts string hashing differently in
	> every interpreter process (see `PYTHONHASHSEED`), so those "seeded" noise
	> realisations were in fact different on every run. The current version uses
	> `zlib.crc32`, which is stable across processes, platforms and Python versions.
	> If you are adapting this code, do not seed from `hash()` on strings.

	Verification built into the notebook. Before any experiment runs, a unit-test
	cell compares the circuit output against the analytic neighbour gradient
	\|f_i − f_{i+1}\|. The largest absolute deviation over N = 8 … 64 is on the order of
	10⁻¹⁴, at the limit of double-precision arithmetic. If this assertion fails, the
	notebook stops.

	Environment. The reference run used:

	\| Component \| Version \|
	\|---\|---\|
	\| Python \| 3.12.3 \|
	\| Qiskit \| 2.5.1 \|
	\| Qiskit Aer \| 0.17.2 \|
	\| NumPy \| 2.4.4 \|
	\| scikit-image \| 0.26.0 \|
	\| OpenCV \| 4.13.0 \|

	The notebook re-prints this fingerprint at run time and writes it to
	`results/environment.json`.

	Expected drift. Quality metrics (Tables I–IV, VI–IX) should reproduce exactly.
	Circuit depth and gate counts (Table V) depend on the Qiskit transpiler and may
	shift by a few percent under a different Qiskit minor version; the qualitative
	conclusion — that state preparation dominates the two-qubit gate cost — is not
	affected.

	---

	## Method in brief

	1. Dataset — eight synthetic shapes plus a binary silhouette, generated
	directly at the target resolution. Ground-truth edges come from a
	morphological boundary of the binary mask.

	Down-sampling a larger image is deliberately avoided: it fragments the
	one-pixel-wide ground-truth map and deletes roughly 54% of its edge pixels,
	which artificially rewards detectors producing fragmented output. The notebook
	prints this loss figure as a diagnostic.

	2. Encoding — QPIE amplitude encoding, c = f / ‖f‖, on n = log₂N qubits.

	3. Circuit — full-boundary QHED on n + 1 qubits:
	H(q₀) → D₍₂^(n+1)₎ → H(q₀), where D is a decrement (amplitude-permutation) gate
	built from a chain of multi-controlled X gates. Odd-index amplitudes carry the
	neighbour gradient.

	4. Evaluation — Pratt Figure of Merit as the primary metric; F1 at a matching
	tolerance of ρ = 1 px as secondary, with the tolerance derived from the BSDS
	scaling rule (0.0075 × image diagonal). Threshold sweep over 33 levels
	(ODS and OIS protocols).

	5. Statistics — Friedman test with Nemenyi critical difference, pairwise
	Wilcoxon tests with Holm correction, and five pre-specified hypotheses reported
	with rank-biserial effect sizes.

	---

	## Runtime breakdown

	\| Stage \| Approx. time \|
	\|---\|---\|
	\| Setup, unit tests, circuit diagrams \| 1 min \|
	\| Experiment 1 — edge quality (64 × 64) \| 1 min \|
	\| Experiment 2 — tolerance and resolution sweeps \| 3 min \|
	\| Experiment 3 — noise robustness (32 × 32) \| 5 min \|
	\| Experiment 4 — circuit cost scaling \| < 1 min \|
	\| Experiment 5 — device noise and shot budget \| 3 min \|
	\| Statistics, export, packaging \| 1 min \|

	The resolution sweep at S = 128 is the single most expensive step. Reduce
	`RES_GRID` if you want a faster pass.

	---

	## Limitations

	- Ground-truth edges are derived from synthetic and silhouette images. No
	human-annotated benchmark (e.g. BSDS500) was used.
	- Experiments run on classical simulation only; no real quantum hardware.
	- The device-noise model assumes uniform depolarisation. Qubit-specific relaxation,
	read-out error and cross-talk are not modelled, and state preparation is treated
	as ideal — so the reported degradation is a lower bound.
	- The `QHED-full+S` variant applies a classical smoothing post-process and is
	therefore a hybrid pipeline, not a fully quantum algorithm.

	---

	## Citation

	If you use this code, please cite both the paper and this archive. See
	`CITATION.cff` for machine-readable metadata.

	---

	## License

	MIT — see `LICENSE`.