quantum autoencoder implementation for v0.1.12

Author: SidRichardsQuantum

CHANGELOG.md

@@ -1,5 +1,28 @@
 # CHANGELOG.md
 
+## [0.1.12] - 10-04-2026
+
+### Added
+
+- Implemented a first-class quantum autoencoder workflow in `qml.autoencoder`
+- Added `autoencoder` CLI support via `python -m qml autoencoder`
+- Added smoke, artifact, CLI, and import coverage for the quantum autoencoder
+- Added autoencoder documentation and example notebook support
+
+### Summary
+
+New core QML capability:
+
+- variational quantum classification (VQC)
+- variational quantum regression (VQR)
+- quantum convolutional neural networks (QCNN)
+- quantum autoencoders
+- quantum kernel methods
+- trainable quantum kernels
+- quantum metric learning
+
+---
+
 ## [0.1.11] - 10-04-2026
 
 ### Added

README.md

@@ -11,6 +11,7 @@ Modular **PennyLane-based quantum machine learning library** implementing reusab
 • Variational quantum classification (VQC)  
 • Variational quantum regression (VQR)  
 • Quantum convolutional neural networks (QCNN)  
+• Quantum autoencoders  
 • Quantum kernel methods  
 • Trainable quantum kernels (kernel-target alignment)  
 • Quantum metric learning (trainable embedding geometry)  
@@ -103,6 +104,27 @@ Learns a small hierarchical quantum classifier using:
 
 ---
 
+## Quantum autoencoder
+
+```python
+from qml.autoencoder import run_quantum_autoencoder
+
+result = run_quantum_autoencoder(
+    n_samples=200,
+    family="correlated",
+    steps=50,
+    plot=True,
+)
+```
+
+Learns a compression map for structured four-qubit state families using:
+
+• a trainable encoder/decoder ansatz  
+• a latent subspace retained across selected qubits  
+• compression and reconstruction fidelity metrics  
+
+---
+
 ## Quantum kernel classifier
 
 ```python
@@ -267,6 +289,7 @@ Run workflows directly:
 ```bash
 python -m qml vqc --steps 50 --plot
 python -m qml qcnn --steps 50 --plot
+python -m qml autoencoder --steps 50 --plot
 python -m qml regression --steps 50 --plot
 python -m qml kernel --plot
 python -m qml trainable-kernel --steps 50 --plot
@@ -308,6 +331,7 @@ Algorithm notes:
 • docs/qml/variational_quantum_classifier.md
 • docs/qml/variational_regression.md
 • docs/qml/qcnn.md
+• docs/qml/autoencoder.md
 • docs/qml/quantum_kernels.md
 • docs/qml/metric_learning.md
 
@@ -316,6 +340,7 @@ Example notebooks:
 • quantum_variational_classifier.ipynb
 • quantum_regressor.ipynb
 • quantum_convolutional_neural_network.ipynb
+• quantum_autoencoder.ipynb
 • quantum_kernel_classifier.ipynb
 • quantum_metric_learning.ipynb
 • classical_vs_quantum_classifier.ipynb
@@ -342,6 +367,9 @@ qml/
     qcnn.py
         quantum convolutional classifier workflows
 
+    autoencoder.py
+        quantum autoencoder workflows
+
     kernel_methods.py
         quantum kernel workflows
 

THEORY.md

@@ -810,6 +810,74 @@ Finite-shot execution approximates behaviour of real quantum hardware.
 
 ---
 
+# Quantum autoencoders
+
+Quantum autoencoders learn a unitary compression map that moves irrelevant
+information into a designated trash subsystem while preserving the informative
+degrees of freedom in a smaller latent subsystem.
+
+Let the input state be
+
+$$
+|\psi(x)\rangle \in \mathcal{H}_A \otimes \mathcal{H}_B
+$$
+
+where:
+
+• $\mathcal{H}_A$ is the retained latent subsystem  
+• $\mathcal{H}_B$ is the trash subsystem  
+
+The encoder aims to transform the state so that the trash subsystem is close to
+a fixed reference state, typically $|0\rangle^{\otimes k}$.
+
+---
+
+## Compression objective
+
+Given encoder unitary $U(\theta)$, the compressed state is
+
+$$
+|\phi(x,\theta)\rangle
+=
+U(\theta)|\psi(x)\rangle.
+$$
+
+Compression succeeds when the trash subsystem factors as
+
+$$
+|\phi(x,\theta)\rangle
+\approx
+|\tilde{\psi}(x)\rangle_A \otimes |0\rangle_B.
+$$
+
+This repository optimizes the probability of measuring the trash subsystem in
+the all-zero state.
+
+---
+
+## Reconstruction
+
+After compression, a decoder can be defined by the adjoint unitary
+
+$$
+U(\theta)^\dagger.
+$$
+
+Applying the decoder gives a reconstructed state
+
+$$
+|\psi_{\mathrm{rec}}(x,\theta)\rangle
+=
+U(\theta)^\dagger U(\theta)|\psi(x)\rangle.
+$$
+
+The implementation reports both:
+
+• compression fidelity on the trash subsystem  
+• reconstruction fidelity on the full state  
+
+---
+
 # References
 
 Schuld, M., Sinayskiy, I., & Petruccione, F. (2015)  

USAGE.md

@@ -261,6 +261,81 @@ Typical fields:
 
 ---
 
+# Quantum autoencoder
+
+Train a quantum autoencoder on a structured family of four-qubit states:
+
+```python
+from qml.autoencoder import run_quantum_autoencoder
+
+result = run_quantum_autoencoder(
+    n_samples=200,
+    noise=0.05,
+    test_size=0.25,
+    seed=123,
+    n_layers=2,
+    latent_qubits=2,
+    steps=50,
+    step_size=0.1,
+    family="correlated",
+    plot=True,
+    save=False,
+)
+```
+
+---
+
+## Parameters
+
+| parameter | description | default |
+| --------- | ----------- | ------- |
+| n_samples | dataset size | 200 |
+| noise | family perturbation level | 0.05 |
+| test_size | test fraction | 0.25 |
+| seed | random seed | 123 |
+| n_layers | autoencoder ansatz depth | 2 |
+| latent_qubits | retained latent qubits | 2 |
+| steps | optimisation steps | 50 |
+| step_size | Adam learning rate | 0.1 |
+| family | state family | "correlated" |
+| plot | show plots | False |
+| save | save JSON + plots | False |
+
+---
+
+## Returned dictionary
+
+Typical fields:
+
+```python
+{
+    "model",
+    "family",
+
+    "seed",
+
+    "n_qubits",
+    "latent_qubits",
+    "trash_qubits",
+
+    "n_layers",
+    "steps",
+    "step_size",
+
+    "loss_history",
+
+    "train_compression_fidelity",
+    "test_compression_fidelity",
+
+    "train_reconstruction_fidelity",
+    "test_reconstruction_fidelity",
+
+    "params",
+}
+```
+
+---
+
 # Quantum kernel classifier
 
 Compute a quantum kernel matrix and train an SVM:
@@ -611,6 +686,8 @@ python -m qml vqc --steps 50 --plot
 
 python -m qml qcnn --steps 50 --plot
 
+python -m qml autoencoder --steps 50 --plot
+
 python -m qml regression --steps 50 --plot
 
 python -m qml kernel --plot

docs/qml/autoencoder.md

@@ -0,0 +1,134 @@
+# Quantum Autoencoder
+
+This note describes the quantum autoencoder workflow implemented in `qml.autoencoder`.
+
+The current implementation is intentionally compact and package-oriented:
+
+• structured four-qubit input state families  
+• a trainable encoder/decoder ansatz  
+• latent and trash subsystem separation  
+• compression and reconstruction fidelity reporting  
+
+---
+
+# Overview
+
+A quantum autoencoder learns a unitary compression map that preserves the
+informative degrees of freedom of a quantum state in a smaller latent subspace.
+
+Rather than predicting labels directly, it learns a transformation that moves
+discardable information into a trash subsystem.
+
+---
+
+# Model structure
+
+Let the input state be
+
+$$
+|\psi(x)\rangle.
+$$
+
+The encoder applies a trainable unitary
+
+$$
+|\phi(x,\theta)\rangle
+=
+U(\theta)|\psi(x)\rangle.
+$$
+
+If compression succeeds, the state factorizes approximately as
+
+$$
+|\phi(x,\theta)\rangle
+\approx
+|\tilde{\psi}(x)\rangle_{\mathrm{latent}}
+\otimes
+|0\rangle_{\mathrm{trash}}.
+$$
+
+The implementation retains a configurable number of latent qubits and measures
+how often the trash subsystem lands in the all-zero basis state.
+
+---
+
+# Training objective
+
+The training signal is the probability of measuring the trash subsystem in
+$|0\rangle^{\otimes k}$.
+
+If
+
+$$
+p_{\mathrm{trash}}(0 \cdots 0 \mid x,\theta)
+$$
+
+denotes that probability, the loss is
+
+$$
+\mathcal{L}(\theta)
+=
+1 - \mathbb{E}_x \left[p_{\mathrm{trash}}(0 \cdots 0 \mid x,\theta)\right].
+$$
+
+Minimizing this loss encourages the encoder to compress the structured state
+family into the latent subsystem.
+
+---
+
+# Reconstruction fidelity
+
+To assess whether useful information is preserved, the workflow also computes a
+reconstruction fidelity by applying the decoder
+
+$$
+U(\theta)^\dagger
+$$
+
+after the encoder and comparing the resulting state to the original state.
+
+This yields two complementary metrics:
+
+• compression fidelity on the trash subsystem  
+• reconstruction fidelity on the full state  
+
+---
+
+# Example usage
+
+```python
+from qml.autoencoder import run_quantum_autoencoder
+
+result = run_quantum_autoencoder(
+    family="correlated",
+    n_samples=200,
+    n_layers=2,
+    latent_qubits=2,
+    steps=50,
+)
+```
+
+Outputs include:
+
+• train/test compression fidelity  
+• train/test reconstruction fidelity  
+• learned ansatz parameters  
+• loss history  
+
+When `save=True`, the workflow writes JSON results and generated figures to:
+
+• `results/autoencoder/`
+• `images/autoencoder/`
+
+---
+
+# State families
+
+The current implementation provides several synthetic state families:
+
+• `correlated`
+• `entangled`
+• `hybrid`
+
+These are designed to provide structured low-dimensional families that are
+meaningful compression targets for a small autoencoder.