QCNN implementation for version 0.1.11

Author: SidRichardsQuantum

CHANGELOG.md

@@ -1,5 +1,29 @@
 # CHANGELOG.md
 
+## [0.1.11] - 10-04-2026
+
+### Added
+
+- Implemented a first-class QCNN workflow in `qml.qcnn`
+- Added `qcnn` CLI support via `python -m qml qcnn`
+- Added QCNN benchmark support in classification benchmarks
+- Added QCNN smoke, CLI, benchmark, and import coverage
+- Added QCNN documentation across README, usage docs, theory notes, and a dedicated algorithm page
+- Added QCNN example notebook: `notebooks/quantum_convolutional_neural_network.ipynb`
+
+### Summary
+
+New core QML capability:
+
+- variational quantum classification (VQC)
+- variational quantum regression (VQR)
+- quantum convolutional neural networks (QCNN)
+- quantum kernel methods
+- trainable quantum kernels
+- quantum metric learning
+
+---
+
 ## [0.1.10] - 10-04-2026
 
 ### Fixed

README.md

@@ -10,6 +10,7 @@ Modular **PennyLane-based quantum machine learning library** implementing reusab
 
 • Variational quantum classification (VQC)  
 • Variational quantum regression (VQR)  
+• Quantum convolutional neural networks (QCNN)  
 • Quantum kernel methods  
 • Trainable quantum kernels (kernel-target alignment)  
 • Quantum metric learning (trainable embedding geometry)  
@@ -82,6 +83,26 @@ result = run_vqr(
 
 ---
 
+## Quantum convolutional neural network
+
+```python
+from qml.qcnn import run_qcnn
+
+result = run_qcnn(
+    n_samples=200,
+    steps=50,
+    plot=True,
+)
+```
+
+Learns a small hierarchical quantum classifier using:
+
+• trainable data embedding across four qubits  
+• shared convolution-style two-qubit blocks  
+• pooling-style entangling reductions before final readout  
+
+---
+
 ## Quantum kernel classifier
 
 ```python
@@ -184,6 +205,7 @@ from qml.benchmarks import compare_classification_models
 result = compare_classification_models(
     models=[
         "vqc",
+        "qcnn",
         "quantum_kernel",
         "trainable_quantum_kernel",
         "logistic_regression",
@@ -203,6 +225,7 @@ Benchmarks accept per-model kwargs:
 result = compare_classification_models(
     models=[
         "vqc",
+        "qcnn",
         "quantum_kernel",
         "trainable_quantum_kernel",
     ],
@@ -243,6 +266,7 @@ Run workflows directly:
 
 ```bash
 python -m qml vqc --steps 50 --plot
+python -m qml qcnn --steps 50 --plot
 python -m qml regression --steps 50 --plot
 python -m qml kernel --plot
 python -m qml trainable-kernel --steps 50 --plot
@@ -253,7 +277,7 @@ Run benchmarks:
 
 ```bash
 python -m qml benchmark classification \
-    --models vqc quantum_kernel svm_classifier logistic_regression \
+    --models vqc qcnn quantum_kernel svm_classifier logistic_regression \
     --seeds 123 456
 ```
 
@@ -283,13 +307,17 @@ Algorithm notes:
 
 • docs/qml/variational_quantum_classifier.md
 • docs/qml/variational_regression.md
+• docs/qml/qcnn.md
 • docs/qml/quantum_kernels.md
+• docs/qml/metric_learning.md
 
 Example notebooks:
 
 • quantum_variational_classifier.ipynb
 • quantum_regressor.ipynb
+• quantum_convolutional_neural_network.ipynb
 • quantum_kernel_classifier.ipynb
+• quantum_metric_learning.ipynb
 • classical_vs_quantum_classifier.ipynb
 
 ---
@@ -311,6 +339,9 @@ qml/
     regression.py
         variational quantum regression workflows
 
+    qcnn.py
+        quantum convolutional classifier workflows
+
     kernel_methods.py
         quantum kernel workflows
 

THEORY.md

@@ -492,6 +492,69 @@ Alignment encourages kernel similarity to reflect class structure.
 
 ---
 
+# Quantum convolutional neural networks
+
+Quantum convolutional neural networks use a hierarchical circuit structure to
+combine local feature extraction with progressive reduction of the active
+degrees of freedom.
+
+A QCNN alternates:
+
+• convolution-style local two-qubit blocks  
+• pooling-style entangling reductions  
+• a final readout on a reduced register  
+
+In the implementation used here, the classifier applies a trainable embedding
+on four qubits, followed by shared convolution blocks on neighbouring pairs,
+then a second-stage convolution on the pooled representation.
+
+---
+
+## Hierarchical structure
+
+Let the initial embedded state be
+
+$$
+|\phi(x, \theta_{\mathrm{emb}})\rangle.
+$$
+
+The QCNN transforms it as
+
+$$
+|\psi(x, \theta)\rangle
+=
+U_{\mathrm{dense}}
+U_{\mathrm{conv},2}
+U_{\mathrm{pool}}
+U_{\mathrm{conv},1}
+|\phi(x, \theta_{\mathrm{emb}})\rangle.
+$$
+
+This differs from a flat variational classifier because information is processed
+through successive local blocks rather than a repeated global ansatz layer.
+
+---
+
+## Binary classification readout
+
+The final prediction is obtained from a Pauli-$Z$ expectation on the readout qubit:
+
+$$
+s(x, \theta) = \langle Z \rangle.
+$$
+
+This is mapped to a class probability by
+
+$$
+p(y=1 \mid x, \theta)
+=
+\frac{1 - s(x, \theta)}{2}.
+$$
+
+Training then minimizes binary cross-entropy over the dataset.
+
+---
+
 # Quantum metric learning
 
 Quantum metric learning aims to learn an embedding geometry in which distances between samples reflect label similarity.

USAGE.md

@@ -156,6 +156,83 @@ result = run_vqr(
 
 ---
 
+# Quantum convolutional neural network (QCNN)
+
+Train a hierarchical quantum classifier on a synthetic dataset:
+
+```python
+from qml.qcnn import run_qcnn
+
+result = run_qcnn(
+    n_samples=200,
+    noise=0.1,
+    test_size=0.25,
+    seed=123,
+    steps=50,
+    step_size=0.1,
+    plot=True,
+    save=False,
+)
+```
+
+---
+
+## Parameters
+
+| parameter | description | default |
+| --------- | ----------- | ------- |
+| n_samples | dataset size | 200 |
+| noise | dataset noise level | 0.1 |
+| test_size | test fraction | 0.25 |
+| seed | random seed | 123 |
+| steps | optimisation steps | 50 |
+| step_size | Adam learning rate | 0.1 |
+| shots | finite-shot sampling | None |
+| plot | show plots | False |
+| save | save JSON + plots | False |
+
+---
+
+## Returned dictionary
+
+Typical fields:
+
+```python
+{
+    "model",
+    "dataset",
+
+    "seed",
+
+    "n_qubits",
+
+    "steps",
+    "step_size",
+
+    "loss_history",
+
+    "train_accuracy",
+    "test_accuracy",
+
+    "params",
+    "embedding_params",
+    "conv1_params",
+    "conv2_params",
+    "dense_params",
+
+    "y_train",
+    "y_test",
+
+    "y_train_pred",
+    "y_test_pred",
+
+    "train_probabilities",
+    "test_probabilities",
+}
+```
+
+---
+
 # Quantum kernel classifier
 
 Compute a quantum kernel matrix and train an SVM:
@@ -423,6 +500,7 @@ from qml.benchmarks import compare_classification_models
 result = compare_classification_models(
     models=[
         "vqc",
+        "qcnn",
         "quantum_kernel",
         "trainable_quantum_kernel",
         "logistic_regression",
@@ -465,6 +543,7 @@ result = compare_classification_models(
 
     models=[
         "vqc",
+        "qcnn",
         "quantum_kernel",
         "trainable_quantum_kernel",
     ],
@@ -502,6 +581,8 @@ Run workflows directly:
 ```bash
 python -m qml vqc --steps 50 --plot
 
+python -m qml qcnn --steps 50 --plot
+
 python -m qml regression --steps 50 --plot
 
 python -m qml kernel --plot
@@ -519,7 +600,7 @@ Classification:
 
 ```bash
 python -m qml benchmark classification \
-    --models vqc quantum_kernel logistic_regression svm_classifier \
+    --models vqc qcnn quantum_kernel logistic_regression svm_classifier \
     --seeds 123 456
 ```
 

docs/qml/benchmarks.md

@@ -42,6 +42,7 @@ Compare multiple classifiers on the same dataset.
 Supported models:
 
 - `vqc`
+- `qcnn`
 - `quantum_kernel`
 - `logistic_regression`
 - `svm_classifier`
@@ -53,7 +54,7 @@ Example:
 from qml.benchmarks import compare_classification_models
 
 result = compare_classification_models(
-    models=["vqc", "quantum_kernel", "svm_classifier"],
+    models=["vqc", "qcnn", "quantum_kernel", "svm_classifier"],
     seeds=[0, 1, 2, 3],
     n_samples=200,
     noise=0.1,
@@ -153,7 +154,7 @@ Classification benchmark:
 
 ```bash
 python -m qml benchmark classification \
-    --models vqc quantum_kernel svm_classifier logistic_regression \
+    --models vqc qcnn quantum_kernel svm_classifier logistic_regression \
     --seeds 123 456 789
 ```
 
@@ -215,6 +216,7 @@ Classification:
 
 ```
 vqc
+qcnn
 quantum_kernel
 logistic_regression
 svm_classifier
@@ -272,6 +274,7 @@ Benchmark utilities call the following workflows:
 Classification:
 
 - `qml.classifiers.run_vqc`
+- `qml.qcnn.run_qcnn`
 - `qml.kernel_methods.run_quantum_kernel_classifier`
 - `qml.classical_baselines.run_logistic_classifier`
 - `qml.classical_baselines.run_svm_classifier`