Quantum Machine Learning (COMP47950)

This submission compares classical, simulated QML (VQC and QSVM), and inference-only IBM Quantum evaluation on a Nim classification task. The main deliverable is the implementation notebook and report; the interactive Nim QML demo is published on Streamlit Community Cloud.

What is in this bundle

• src/qml_project/ — importable package (circuits, training, baselines, device helpers, Nim utilities).
• notebooks/ — primary submission: notebooks/qml_project.ipynb (implementation and report).
• apps/nim_demo/ — Streamlit demonstration (see apps/nim_demo/README.md for layout, behaviour, and Streamlit Cloud deploy steps).

Also included: Makefile, pyproject.toml, uv.lock.

Prerequisites

• Python 3.10 (matches the default in the Makefile).
• uv — install from the vendor instructions, for example:

curl -LsSf https://astral.sh/uv/install.sh | sh

Recommended setup (full notebook)

From the repository root, create the environment that includes Jupyter, MLflow, Qiskit, Aer, and IBM Runtime, then start the notebook:

make env-full
make run-notebook-full

The qml_project package is installed from src/ into that environment.

Lighter dependency sets (Qiskit-only, device-only) exist as other make env-* targets in the Makefile if you need them.

Optional: Jupyter kernel for .venv-full

If you use Jupyter outside the make run-notebook-full flow, register a kernel (then pick Python (qml-full) in the kernel menu):

UV_PROJECT_ENVIRONMENT=.venv-full uv run python -m ipykernel install --user \
  --name=qml-full --display-name="Python (qml-full)"

Streamlit demo (same venv as the full notebook)

make run-demo in the Makefile uses a different virtualenv (.venv-qiskit). If you only created .venv-full, run the demo with:

UV_PROJECT_ENVIRONMENT=.venv-full uv run streamlit run apps/nim_demo/app.py

Alternatively, run make env-qiskit and then make run-demo.

Published demo (Streamlit Community Cloud)

https://nim-quantum-ml.streamlit.app/ — play Nim against VQC, QSVM, or classical models; Learn pages mirror the report narrative. Maintainer notes: apps/nim_demo/README.md. Cloud uses apps/nim_demo/environment.yml (Python 3.10); if the build log shows 3.14 or pyarrow compile errors, delete the app and redeploy after pulling the latest main.

MLflow UI (optional)

After make env-full, you can browse local experiment data (if present) with:

UV_PROJECT_ENVIRONMENT=.venv-full uv run mlflow ui

then open http://localhost:5000. The graded narrative lives in the notebook outputs; MLflow is not required to read the report.