Quick Start Guide

Get up and running with QGANS Pro in minutes! This guide will walk you through your first quantum GAN experiment.

🚀 5-Minute Quantum GAN

1. Import the Framework

import torch
from qgans_pro import (
    QuantumGenerator, QuantumDiscriminator, 
    QuantumGAN, get_data_loader
)

2. Load Data

# Load Fashion-MNIST dataset
train_loader = get_data_loader(
    dataset_name="fashion-mnist",
    batch_size=64,
    train=True,
    download=True
)

3. Create Quantum Models

# Define quantum circuit parameters
n_qubits = 8
n_layers = 3
input_dim = 28 * 28  # Fashion-MNIST image size

# Create quantum generator
generator = QuantumGenerator(
    n_qubits=n_qubits,
    n_layers=n_layers,
    output_dim=input_dim,
    backend="qiskit",  # or "pennylane"
    device="aer_simulator"
)

# Create quantum discriminator
discriminator = QuantumDiscriminator(
    input_dim=input_dim,
    n_qubits=n_qubits,
    n_layers=n_layers,
    backend="qiskit",
    device="aer_simulator"
)

4. Initialize Training

# Set up the quantum GAN trainer
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")

qgan = QuantumGAN(
    generator=generator,
    discriminator=discriminator,
    device=device,
    lr_g=0.001,
    lr_d=0.001
)

5. Train the Model

# Train for 50 epochs
qgan.train(
    dataloader=train_loader,
    epochs=50,
    save_interval=10,
    sample_interval=5
)

6. Generate Samples

# Generate 64 synthetic samples
synthetic_samples = qgan.generate_samples(64)

# Visualize results
from qgans_pro.utils import plot_generated_samples
plot_generated_samples(synthetic_samples, title="Quantum GAN Results")

📋 Complete Example

Here's a complete working example:

import torch
import matplotlib.pyplot as plt
from qgans_pro import (
    QuantumGenerator, QuantumDiscriminator, QuantumGAN,
    get_data_loader, plot_generated_samples
)

# Configuration
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
n_qubits = 6
n_layers = 2
epochs = 30

# Load data
train_loader = get_data_loader("fashion-mnist", batch_size=32, train=True)

# Create models
generator = QuantumGenerator(
    n_qubits=n_qubits, n_layers=n_layers, output_dim=784,
    backend="qiskit", device="aer_simulator"
)

discriminator = QuantumDiscriminator(
    input_dim=784, n_qubits=n_qubits, n_layers=n_layers,
    backend="qiskit", device="aer_simulator"
)

# Initialize trainer
qgan = QuantumGAN(generator, discriminator, device=device)

# Train
print("🚀 Starting training...")
qgan.train(train_loader, epochs=epochs, sample_interval=10)

# Generate and visualize
print("🎨 Generating samples...")
samples = qgan.generate_samples(16)
plot_generated_samples(samples, title="My First Quantum GAN!")

print("✅ Complete!")

🔧 Configuration Options

Backend Selection

Choose between quantum computing frameworks:

QiskitPennyLane

generator = QuantumGenerator(
    backend="qiskit",
    device="aer_simulator"  # or "qasm_simulator", "ibmq_qasm_simulator"
)

generator = QuantumGenerator(
    backend="pennylane",
    device="default.qubit"  # or "qiskit.aer", "cirq.simulator"
)

Circuit Architecture

Customize your quantum circuits:

# Small circuit (fast training)
generator = QuantumGenerator(n_qubits=4, n_layers=2)

# Medium circuit (balanced)
generator = QuantumGenerator(n_qubits=8, n_layers=3)

# Large circuit (high capacity)
generator = QuantumGenerator(n_qubits=12, n_layers=4)

Training Parameters

Fine-tune training behavior:

qgan = QuantumGAN(
    generator=generator,
    discriminator=discriminator,
    lr_g=0.0005,        # Generator learning rate
    lr_d=0.001,         # Discriminator learning rate
    beta1=0.5,          # Adam optimizer beta1
    beta2=0.999,        # Adam optimizer beta2
    lambda_gp=10        # Gradient penalty coefficient
)

📊 Evaluation

Evaluate your quantum GAN's performance:

from qgans_pro.utils import FIDScore, InceptionScore, QuantumFidelity

# Calculate FID score
fid_metric = FIDScore(device=device)
fid_score = fid_metric(real_samples, generated_samples)
print(f"FID Score: {fid_score:.2f}")

# Calculate Inception Score
is_metric = InceptionScore(device=device)
is_mean, is_std = is_metric(generated_samples)
print(f"Inception Score: {is_mean:.2f} ± {is_std:.2f}")

# Quantum-specific metrics
qf_metric = QuantumFidelity(device=device)
quantum_metrics = qf_metric(real_samples, generated_samples)
print(f"Quantum Fidelity: {quantum_metrics['fidelity']:.4f}")

🎯 Next Steps

Now that you've created your first quantum GAN, explore more advanced features:

1. Tabular Data Generation - Generate synthetic tabular datasets
2. Bias Mitigation - Use quantum GANs for fairness
3. Training Guide - Advanced training techniques
4. Theory - Understand the quantum advantage

🆘 Common Issues

Memory Issues

If you encounter memory issues:

# Reduce batch size
train_loader = get_data_loader("fashion-mnist", batch_size=16)

# Use fewer qubits
generator = QuantumGenerator(n_qubits=4, n_layers=2)

Slow Training

To speed up training:

# Use classical discriminator
from qgans_pro import ClassicalDiscriminator
discriminator = ClassicalDiscriminator(input_dim=784)

# Reduce circuit complexity
generator = QuantumGenerator(n_qubits=6, n_layers=2)

Backend Errors

If quantum backend fails:

# Check backend availability
from qgans_pro.backends import QiskitBackend
backend = QiskitBackend()
print(f"Available: {backend.is_available()}")

# Use simulator instead of real hardware
generator = QuantumGenerator(backend="qiskit", device="aer_simulator")

Pro Tip

Start with small quantum circuits (4-6 qubits) and gradually increase complexity as you become familiar with the framework.

Hardware Requirements

Quantum circuit simulation can be computationally intensive. For circuits with >10 qubits, consider using GPU acceleration or cloud quantum computing services.