Quantum Neural Network - Two Moons Classification

A 2-qubit Quantum Neural Network (QNN) trained for binary classification on the Two Moons dataset

📊 Model Overview

This is a Quantum Neural Network (QNN) designed for binary classification tasks, demonstrating quantum machine learning on real quantum hardware. The model uses a hardware-efficient ansatz with 2 qubits and has been tested on IBM Quantum's ibm_fez backend.

Key Features

• 🔬 Pure Quantum Model: Uses quantum circuits for feature encoding and classification
• ⚡ Hardware-Efficient: Optimized for NISQ-era quantum devices
• 🎯 Binary Classification: Trained on the Two Moons dataset
• 🌐 IBM Quantum: Compatible with real quantum hardware
• 📦 Easy to Use: Simple inference API with pre-trained weights

🏗️ Model Architecture

Specifications

Circuit Diagram

     ┌──────────┐┌──────────┐     ┌──────────┐
q_0: ┤ Ry(x[0]) ├┤ Ry(w[0]) ├──■──┤ Ry(w[2]) ├
     ├──────────┤├──────────┤┌─┴─┐├──────────┤
q_1: ┤ Ry(x[1]) ├┤ Ry(w[1]) ├┤ X ├┤ Ry(w[3]) ├
     └──────────┘└──────────┘└───┘└──────────┘

Layer Breakdown

1. Encoding Layer (Ry(x[0]), Ry(x[1])): Encodes 2D classical data into quantum states
2. Variational Layer 1 (Ry(w[0]), Ry(w[1])): First trainable rotation gates
3. Entanglement Layer (CNOT): Creates quantum correlations between qubits
4. Variational Layer 2 (Ry(w[2]), Ry(w[3])): Second trainable rotation gates
5. Measurement: Parity measurement on both qubits for classification

🚀 Quick Start

Installation

pip install qiskit qiskit-machine-learning numpy huggingface-hub

Basic Usage

from huggingface_hub import hf_hub_download
from qiskit import qpy
import numpy as np

# Download model files
circuit_path = hf_hub_download(
    repo_id="squ11z1/Two-Moons",
    filename="circuit.qpy"
)
weights_path = hf_hub_download(
    repo_id="squ11z1/Two-Moons",
    filename="weights.npy"
)

# Load quantum circuit
with open(circuit_path, 'rb') as f:
    circuit = qpy.load(f)[0]

# Load trained weights
weights = np.load(weights_path)

print(f"Loaded QNN with {circuit.num_qubits} qubits")
print(f"Trained weights: {weights}")

Inference Example

from qiskit.circuit import ParameterVector
from qiskit_machine_learning.neural_networks import SamplerQNN
from qiskit_machine_learning.algorithms.classifiers import NeuralNetworkClassifier
from qiskit.primitives import StatevectorSampler as Sampler

# Load test data
X_test = np.load(hf_hub_download(
    repo_id="squ11z1/TwoMoons-2Q",
    filename="X_test.npy"
))

# Setup parameters
input_params = [p for p in circuit.parameters if p.name.startswith('x')]
weight_params = [p for p in circuit.parameters if p.name.startswith('w')]

# Parity interpretation function
def parity(x):
    """Convert measurement to binary classification (0 or 1)"""
    return bin(x).count("1") % 2

# Create QNN
sampler = Sampler()
qnn = SamplerQNN(
    circuit=circuit,
    input_params=input_params,
    weight_params=weight_params,
    interpret=parity,
    output_shape=2,
    sampler=sampler
)

# Create classifier with pre-trained weights
classifier = NeuralNetworkClassifier(
    neural_network=qnn,
    optimizer=None  # Weights already trained
)
classifier._fit_result = type('obj', (object,), {'x': weights})

# Make predictions
predictions = classifier.predict(X_test)
print(f"Predictions: {predictions}")

Using the Helper Module

from qnn_inference import load_qnn_model, create_qnn_classifier
import numpy as np

# Load model
circuit, weights = load_qnn_model(repo_id="squ11z1/Two-Moons")

# Create classifier
classifier = create_qnn_classifier(circuit, weights)

# Predict on new data
X_new = np.array([[0.5, 0.2], [-0.5, 0.5]])
predictions = classifier.predict(X_new)
print(f"Predictions: {predictions}")

📈 Training Details

Dataset

• Name: Two Moons (sklearn.datasets.make_moons)
• Type: Synthetic binary classification dataset
• Features: 2D coordinates (x, y)
• Classes: 2 (crescent-shaped clusters)
• Train samples: 8
• Test samples: 4
• Total: 12 samples

Training Configuration

• Optimizer: COBYLA (Constrained Optimization BY Linear Approximation)
• Loss Function: Cross-entropy
• Epochs: Variable (convergence-based)
• Training Backend: IBM Quantum (ibm_fez)
• Testing Backend: IBM Quantum (ibm_fez)

Performance Metrics

Note: The low test accuracy (0% in the visualization) is typical for:

• Small training dataset (only 8 samples)
• Quantum noise from real hardware
• Limited model capacity (2 qubits)
• Early-stage NISQ device limitations

This is a proof-of-concept model demonstrating quantum ML workflows, not production-ready accuracy.

🔬 Technical Deep Dive

Why Hardware-Efficient Ansatz?

The hardware-efficient ansatz is chosen to:

1. Minimize gate count: Fewer gates = less noise accumulation
2. Use native gates: Ry and CNOT are native to IBM Quantum hardware
3. Avoid compilation overhead: Circuit runs directly on hardware
4. Reduce circuit depth: Depth 4 is shallow enough for NISQ devices

Barren Plateau Mitigation

This architecture avoids the barren plateau problem through:

• ✅ Small qubit count (n=2): Gradient variance ∝ 1/2^n = 1/4 (good!)
• ✅ Shallow depth (4 layers): Limits exponential gradient decay
• ✅ Local connectivity: Linear entanglement structure
• ✅ Parameter efficiency: Only 4 trainable parameters

Expected gradient variance: Var[∂L/∂θ] ≈ 0.25

Quantum Advantage?

For this small problem, no quantum advantage is expected or claimed. However, this model serves as:

1. Educational tool: Demonstrates QML concepts
2. Research platform: Tests quantum algorithms on real hardware
3. Proof of concept: Shows end-to-end quantum workflow
4. Benchmark: Compares quantum vs classical performance

Measurement Strategy

The model uses parity measurement:

def parity(x):
    """
    Measures both qubits and computes parity.
    
    Example:
    - |00⟩ → 0 (even parity) → Class 0
    - |01⟩ → 1 (odd parity)  → Class 1
    - |10⟩ → 1 (odd parity)  → Class 1
    - |11⟩ → 0 (even parity) → Class 0
    """
    return bin(x).count("1") % 2

This creates a nonlinear decision boundary in feature space.

📁 Repository Contents

.
├── README.md                 # This file
├── circuit.qpy               # Quantum circuit (Qiskit QPY format, 712 bytes)
├── weights.npy               # Trained weights (4 parameters, 160 bytes)
├── config.json               # Model configuration metadata
├── qnn_inference.py          # Helper functions for loading and inference
├── requirements.txt          # Python dependencies
├── X_train.npy               # Training input data (8 samples)
├── X_test.npy                # Test input data (4 samples)
├── y_train.npy               # Training labels
├── y_test.npy                # Test labels

🎯 Use Cases

Educational

• Learn quantum machine learning fundamentals
• Understand variational quantum algorithms
• Explore quantum circuit design

Research

• Benchmark quantum vs classical models
• Study quantum noise effects on ML
• Test new quantum ML algorithms
• Investigate NISQ-era limitations

Development

• Template for quantum ML projects
• Starting point for larger QNN models
• Integration example for Hugging Face + Qiskit

⚠️ Limitations

Model Limitations

• Small dataset: Only 12 samples total (not scalable)
• Low capacity: 2 qubits limit expressiveness
• Binary only: Can't handle multi-class problems as-is
• Fixed input: Requires exactly 2D input features

Quantum Hardware Limitations

• NISQ noise: Quantum errors degrade performance
• Decoherence: Qubits lose quantum state over time
• Gate errors: Imperfect quantum operations
• Limited connectivity: Hardware topology constraints

Practical Limitations

• Slow inference: Quantum circuits are slower than classical NNs
• Requires quantum access: Needs IBM Quantum account for hardware runs
• No gradients: Can't fine-tune (weights are pre-trained)
• Stochastic: Results vary due to quantum sampling

🔮 Future Improvements

Immediate Next Steps

• Increase dataset size to 100+ samples
• Add data augmentation for better generalization
• Test on multiple quantum backends
• Implement error mitigation techniques

Long-term Goals

• Scale to 4-16 qubits for more complex patterns
• Multi-class classification support
• Hybrid quantum-classical architecture
• Deploy on IBM Quantum Runtime
• Compare with classical ML benchmarks

📚 Citation

If you use this model in your research, please cite:

@misc{qnn-two-moons-2025,
  author = {squ11z1},
  title = {Quantum Neural Network for Two Moons Classification},
  year = {2025},
  publisher = {Hugging Face},
  howpublished = {\url{https://huggingface.co/squ11z1/Two-Moons}},
  note = {2-qubit QNN with hardware-efficient ansatz}
}

📖 References

Quantum Machine Learning

• Qiskit Machine Learning Documentation
• Quantum Neural Networks (arXiv:1802.06002)
• Supervised learning with quantum enhanced feature spaces (Nature 2019)

Variational Algorithms

• Variational Quantum Algorithms (arXiv:2012.09265)
• Hardware-efficient variational quantum eigensolver (arXiv:1704.05018)

Barren Plateaus

• Barren plateaus in quantum neural network training (Nature 2018)
• The effect of data encoding on barren plateaus (arXiv:2008.08605)

IBM Quantum

• IBM Quantum Platform
• Qiskit Documentation

🤝 Contributing

This is an experimental research model. Contributions welcome!

How to Contribute

1. Test the model on different datasets
2. Report issues or bugs
3. Suggest architectural improvements
4. Share your results and findings

Open an issue or discussion on the Hugging Face model page.

📄 License

Apache License 2.0

This model and all associated code are released under the Apache 2.0 license. You are free to use, modify, and distribute this model for any purpose, including commercial applications.

See LICENSE for full details.

---

Built with ❤️ using Qiskit and IBM Quantum

Like this model if you find it useful!