QML-qcnn-medmnist

This repository provides the reference implementation for a hybrid quantum–classical convolutional neural network (QCNN) applied to medMNIST image classification, developed as a project for the Quantum Machine Learning course. The project is authored by Antonio Mosca and Leonardo Tomei.

The code implements a patch-based quantum feature extraction pipeline using Qiskit, combined with classical training and evaluation using PyTorch. The repository is designed to support reproducible experimentation, command-line execution, and structured reporting.

Exam report: QML-exam.report.pdf is the report of the project presented for the QML exam and includes an in-depth discussion of architecture and results.

---

Scope

• Target datasets are from the medMNIST benchmark (e.g. bloodmnist).
• Images are preprocessed into local patches processed by quantum circuits.
• Quantum features are extracted at patch level and aggregated into a compact classifier.
• Training, evaluation, and visualization are handled via modular CLIs.
• The pipeline supports deterministic execution via explicit seeding.

---

Installation

Create and activate a virtual environment, then install the packages in editable mode:

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Quickstart

End-to-end execution using the provided command-line interfaces:

qcnn-preprocess --dataset bloodmnist
qcnn-train --dataset bloodmnist --epochs 5 --stride 3
qcnn-report --dataset bloodmnist --logdir logs/bloodmnist_run_001 --stride 3
qcnn-heatmap --dataset bloodmnist --logdir logs/bloodmnist_run_001 --idx 0 --stride 3
qcnn-plot-curves --logdir logs/bloodmnist_run_001

For --logdir, all analysis CLIs accept either:

• a run directory path (absolute or relative), e.g. logs/bloodmnist_run_001;
• a run folder name inside --logs-dir, e.g. bloodmnist_run_001.

Repository Layout

• src/: Python package source (src.datasets, src.models, src.quantum, src.scripts, src.training, src.utils).
• tests/: automated test suite.
• notebooks/QML-qcnn-medmnist_pipeline.ipynb: end-to-end workflow notebook.
• QML-exam.report.pdf: project exam report document.
• pyproject.toml: package metadata, dependencies, and CLI entry points.

Runtime Outputs

• data/raw/: downloaded medMNIST archives.
• data/processed/<dataset>/: preprocessed tensors (train.pt, val.pt, test.pt).
• logs/<dataset>_run_XXX/: run metrics and model checkpoints.
• reports/<dataset>_run_XXX/: confusion matrix, heatmaps, learning curves, predictions, and report metadata.

data/, logs/, and reports/ are runtime artifact directories and are ignored by Git, except for .gitkeep placeholders.

Reproducibility

• Use --seed in CLI commands to initialize Python, NumPy, PyTorch, and Qiskit randomness.
• PYTHONHASHSEED is set by the seed utility for deterministic hashing behavior.
• Set QCNN_CPUS to control process-level parallelism in quantum convolution workers.

Developer

• Remove local test/build artifacts with bash scripts/clean_artifacts.sh.

Dataset Acknowledgment

This project uses medMNIST. Datasets are downloaded at runtime and are not tracked in version control.

Authors

• Antonio Mosca
• Leonardo Tomei

License

This project is licensed under the MIT License.