Quantum Neural Network - Two Moons Classification
twomoons
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
Feature Value Qubits 2 Circuit Depth 4 layers Total Parameters 6 (2 input + 4 trainable) Trainable Parameters 4 Gates 6× Ry + 1× CNOT Entanglement Linear topology Ansatz Type Hardware-Efficient Backend IBM Quantum (ibm_fez)
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
Encoding Layer (Ry(x[0]), Ry(x[1])): Encodes 2D classical data into quantum statesVariational Layer 1 (Ry(w[0]), Ry(w[1])): First trainable rotation gatesEntanglement Layer (CNOT): Creates quantum correlations between qubitsVariational Layer 2 (Ry(w[2]), Ry(w[3])): Second trainable rotation gatesMeasurement : Parity measurement on both qubits for classification
🚀 Quick Start
Installation
pip install qiskit qiskit-machine-learning numpy huggingface-hubBasic Usage
1 from huggingface_hub import hf_hub_download
2 from qiskit import qpy
3 import numpy as np
4
5 # Download model files
6 circuit_path = hf_hub_download (
7 repo_id = "squ11z1/Two-Moons" ,
8 filename = "circuit.qpy"
9 )
10 weights_path = hf_hub_download (
11 repo_id = "squ11z1/Two-Moons" ,
12 filename = "weights.npy"
13 )
14
15 # Load quantum circuit
16 with open ( circuit_path , 'rb' ) as f :
17 circuit = qpy . load ( f ) [ 0 ]
18
19 # Load trained weights
20 weights = np . load ( weights_path )
21
22 print ( f"Loaded QNN with { circuit . num_qubits } qubits" )
23 print ( f"Trained weights: { weights } " )
Inference Example
1 from qiskit . circuit import ParameterVector
2 from qiskit_machine_learning . neural_networks import SamplerQNN
3 from qiskit_machine_learning . algorithms . classifiers import NeuralNetworkClassifier
4 from qiskit . primitives import StatevectorSampler as Sampler
5
6 # Load test data
7 X_test = np . load ( hf_hub_download (
8 repo_id = "squ11z1/TwoMoons-2Q" ,
9 filename = "X_test.npy"
10 ) )
11
12 # Setup parameters
13 input_params = [ p for p in circuit . parameters if p . name . startswith ( 'x' ) ]
14 weight_params = [ p for p in circuit . parameters if p . name . startswith ( 'w' ) ]
15
16 # Parity interpretation function
17 def parity ( x ) :
18 """Convert measurement to binary classification (0 or 1)"""
19 return bin ( x ) . count ( "1" ) % 2
20
21 # Create QNN
22 sampler = Sampler ( )
23 qnn = SamplerQNN (
24 circuit = circuit ,
25 input_params = input_params ,
26 weight_params = weight_params ,
27 interpret = parity ,
28 output_shape = 2 ,
29 sampler = sampler
30 )
31
32 # Create classifier with pre-trained weights
33 classifier = NeuralNetworkClassifier (
34 neural_network = qnn ,
35 optimizer = None # Weights already trained
36 )
37 classifier . _fit_result = type ( 'obj' , ( object , ) , { 'x' : weights } )
38
39 # Make predictions
40 predictions = classifier . predict ( X_test )
41 print ( f"Predictions: { predictions } " )
Using the Helper Module
1 from qnn_inference import load_qnn_model , create_qnn_classifier
2 import numpy as np
3
4 # Load model
5 circuit , weights = load_qnn_model ( repo_id = "squ11z1/Two-Moons" )
6
7 # Create classifier
8 classifier = create_qnn_classifier ( circuit , weights )
9
10 # Predict on new data
11 X_new = np . array ( [ [ 0.5 , 0.2 ] , [ - 0.5 , 0.5 ] ] )
12 predictions = classifier . predict ( X_new )
13 print ( f"Predictions: { predictions } " )
📈 Training Details
Dataset
Name: Two Moons (sklearn.datasets.make_moons)Type: Synthetic binary classification datasetFeatures: 2D coordinates (x, y)Classes: 2 (crescent-shaped clusters)Train samples: 8Test samples: 4Total: 12 samples
Training Configuration
Optimizer: COBYLA (Constrained Optimization BY Linear Approximation)Loss Function: Cross-entropyEpochs: Variable (convergence-based)Training Backend: IBM Quantum (ibm_fez)Testing Backend: IBM Quantum (ibm_fez)
Performance Metrics
Metric Value Notes Test Accuracy 0-75% Varies by noise and seed Train Accuracy ~87.5% On 8 training samples Baseline (Random) 50% Random guessing Classical MLP ~100% For comparison
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:
Minimize gate count : Fewer gates = less noise accumulationUse native gates : Ry and CNOT are native to IBM Quantum hardwareAvoid compilation overhead : Circuit runs directly on hardwareReduce 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:
Educational tool : Demonstrates QML conceptsResearch platform : Tests quantum algorithms on real hardwareProof of concept : Shows end-to-end quantum workflowBenchmark : Compares quantum vs classical performance
Measurement Strategy
The model uses parity measurement :
1 def parity ( x ) :
2 """
3 Measures both qubits and computes parity.
4
5 Example:
6 - |00⟩ → 0 (even parity) → Class 0
7 - |01⟩ → 1 (odd parity) → Class 1
8 - |10⟩ → 1 (odd parity) → Class 1
9 - |11⟩ → 0 (even parity) → Class 0
10 """
11 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 expressivenessBinary only : Can't handle multi-class problems as-isFixed input : Requires exactly 2D input features
Quantum Hardware Limitations
NISQ noise : Quantum errors degrade performanceDecoherence : Qubits lose quantum state over timeGate errors : Imperfect quantum operationsLimited connectivity : Hardware topology constraints
Practical Limitations
Slow inference : Quantum circuits are slower than classical NNsRequires quantum access : Needs IBM Quantum account for hardware runsNo gradients : Can't fine-tune (weights are pre-trained)Stochastic : Results vary due to quantum sampling
🔮 Future Improvements
Immediate Next Steps
Long-term Goals
📚 Citation
If you use this model in your research, please cite:
1 @misc{qnn-two-moons-2025,
2 author = {squ11z1},
3 title = {Quantum Neural Network for Two Moons Classification},
4 year = {2025},
5 publisher = {Hugging Face},
6 howpublished = {\url{https://huggingface.co/squ11z1/Two-Moons}},
7 note = {2-qubit QNN with hardware-efficient ansatz}
8 }
📖 References
Quantum Machine Learning
Variational Algorithms
Barren Plateaus
IBM Quantum
🤝 Contributing
This is an experimental research model. Contributions welcome!
How to Contribute
Test the model on different datasets
Report issues or bugs
Suggest architectural improvements
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!
