Skip to content

Models API Reference

This module contains the core quantum and classical generative models in QGANS Pro.

QuantumGenerator

::: qgans_pro.models.QuantumGenerator options: show_root_heading: true show_source: true heading_level: 3

Usage Examples

Basic Quantum Generator

from qgans_pro import QuantumGenerator

# Create quantum generator with 8 qubits and 3 layers
generator = QuantumGenerator(
    n_qubits=8,
    n_layers=3,
    output_dim=784,  # 28x28 MNIST images
    backend="qiskit",
    device="aer_simulator"
)

# Generate samples
import torch
latent = torch.randn(32, 8)  # Batch size 32, 8 latent dimensions
generated_samples = generator(latent)
print(f"Generated shape: {generated_samples.shape}")  # [32, 784]

Advanced Configuration

# Advanced quantum generator with custom encoding
generator = QuantumGenerator(
    n_qubits=12,
    n_layers=4,
    output_dim=784,
    backend="pennylane",
    device="default.qubit",
    encoding_type="angle",  # Angle encoding
    post_processing="mlp",  # MLP post-processing
    entanglement_pattern="circular",
    parameter_sharing=True
)

# Access quantum circuit properties
print(f"Circuit depth: {generator.circuit_depth}")
print(f"Parameter count: {generator.parameter_count}")
print(f"Entanglement capability: {generator.entanglement_capability}")

Methods

forward(latent_input)

Forward pass through the quantum generator.

Parameters:

  • latent_input (torch.Tensor): Input latent vector of shape (batch_size, n_qubits)

Returns:

  • torch.Tensor: Generated samples of shape (batch_size, output_dim)

get_circuit()

Get the quantum circuit representation.

Returns:

  • Circuit object (backend-dependent)

get_parameters()

Get current quantum circuit parameters.

Returns:

  • torch.Tensor: Circuit parameters

set_parameters(params)

Set quantum circuit parameters.

Parameters:

  • params (torch.Tensor): New circuit parameters

Properties

circuit_depth

Get the depth of the quantum circuit.

parameter_count

Get the total number of trainable parameters.

entanglement_capability

Measure of the circuit's entangling capability.

QuantumDiscriminator

::: qgans_pro.models.QuantumDiscriminator options: show_root_heading: true show_source: true heading_level: 3

Usage Examples

Basic Quantum Discriminator

from qgans_pro import QuantumDiscriminator

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

# Classify samples
real_data = torch.randn(32, 784)
predictions = discriminator(real_data)
print(f"Predictions shape: {predictions.shape}")  # [32, 1]

Advanced Discriminator Features

# Discriminator with gradient penalty support
discriminator = QuantumDiscriminator(
    input_dim=784,
    n_qubits=10,
    n_layers=4,
    backend="pennylane",
    device="default.qubit",
    gradient_penalty=True,
    spectral_norm=True,
    dropout_rate=0.1
)

# Enable gradient penalty calculation
discriminator.enable_gradient_penalty()

ClassicalGenerator

::: qgans_pro.models.ClassicalGenerator options: show_root_heading: true show_source: true heading_level: 3

Usage Examples

from qgans_pro import ClassicalGenerator

# Create classical baseline generator
generator = ClassicalGenerator(
    latent_dim=100,
    output_dim=784,
    hidden_dims=[256, 512, 1024],
    activation="leaky_relu",
    batch_norm=True,
    dropout_rate=0.2
)

# Generate samples
latent = torch.randn(32, 100)
generated_samples = generator(latent)

ClassicalDiscriminator

::: qgans_pro.models.ClassicalDiscriminator options: show_root_heading: true show_source: true heading_level: 3

Usage Examples

from qgans_pro import ClassicalDiscriminator

# Create classical discriminator
discriminator = ClassicalDiscriminator(
    input_dim=784,
    hidden_dims=[1024, 512, 256],
    activation="leaky_relu",
    batch_norm=True,
    spectral_norm=True
)

# Classify samples
real_data = torch.randn(32, 784)
predictions = discriminator(real_data)

Model Utilities

Model Factory

Create models with predefined configurations:

from qgans_pro.models import create_model

# Create quantum model with preset configuration
generator = create_model(
    model_type="quantum_generator",
    preset="efficient",  # "efficient", "balanced", "high_capacity"
    output_dim=784
)

# Create hybrid model
hybrid_generator = create_model(
    model_type="hybrid_generator",
    quantum_layers=2,
    classical_layers=3,
    output_dim=784
)

Model Comparison

Compare different model architectures:

from qgans_pro.models import ModelComparator

comparator = ModelComparator()

# Add models to compare
comparator.add_model("Quantum", quantum_generator)
comparator.add_model("Classical", classical_generator)
comparator.add_model("Hybrid", hybrid_generator)

# Get comparison metrics
comparison = comparator.compare(
    metrics=["parameters", "flops", "memory", "expressivity"]
)

print(comparison.to_table())

Model Serialization

Save and load trained models:

from qgans_pro.models import save_model, load_model

# Save model with metadata
save_model(
    model=quantum_generator,
    path="quantum_generator.pth",
    metadata={
        "training_epochs": 100,
        "dataset": "fashion-mnist",
        "performance": {"fid": 15.2, "is": 7.8}
    }
)

# Load model
loaded_generator, metadata = load_model("quantum_generator.pth")
print(f"Model trained for {metadata['training_epochs']} epochs")

Advanced Features

Circuit Optimization

Optimize quantum circuits for better performance:

from qgans_pro.models.optimization import CircuitOptimizer

# Optimize quantum generator circuit
optimizer = CircuitOptimizer()
optimized_generator = optimizer.optimize(
    model=quantum_generator,
    target_depth=10,
    preserve_expressivity=True
)

print(f"Original depth: {quantum_generator.circuit_depth}")
print(f"Optimized depth: {optimized_generator.circuit_depth}")

Noise Modeling

Add realistic quantum noise to models:

from qgans_pro.models.noise import NoiseModel

# Add noise to quantum generator
noise_model = NoiseModel(
    gate_error_rates={"rx": 0.001, "ry": 0.001, "cnot": 0.01},
    decoherence_times={"t1": 50e-6, "t2": 20e-6}
)

noisy_generator = noise_model.apply(quantum_generator)

Transfer Learning

Use pre-trained quantum circuits:

from qgans_pro.models.transfer import transfer_quantum_weights

# Transfer weights from pre-trained model
source_generator = load_model("pretrained_generator.pth")[0]
target_generator = QuantumGenerator(n_qubits=8, n_layers=3, output_dim=784)

transfer_quantum_weights(
    source=source_generator,
    target=target_generator,
    layer_mapping="auto"  # or custom mapping
)

Best Practices

Model Selection Guidelines

Choose the appropriate model based on your use case:

  1. Quantum Generator + Quantum Discriminator: Maximum quantum advantage, highest expressivity
  2. Quantum Generator + Classical Discriminator: Balanced approach, faster training
  3. Classical Generator + Quantum Discriminator: Novel discriminative features
  4. Hybrid Models: Combines quantum and classical advantages

Performance Optimization

Tips for optimizing model performance:

# Use appropriate circuit depth
n_layers = min(4, n_qubits // 2)  # Rule of thumb

# Enable gradient checkpointing for memory efficiency
generator.enable_gradient_checkpointing()

# Use mixed precision training
generator.half()  # Convert to half precision

# Optimize backend settings
generator.set_backend_config({
    "shots": 1024,
    "optimization_level": 2,
    "memory_efficient": True
})