Skip to content

Configuration Guide

Learn how to configure QGANS Pro for optimal performance across different quantum backends, hardware setups, and use cases.

🎛️ Core Configuration

Environment Setup

Set up your environment variables for optimal performance:

# Set quantum backend preferences
export QGANS_DEFAULT_BACKEND="qiskit"
export QGANS_DEFAULT_DEVICE="aer_simulator"

# GPU configuration
export CUDA_VISIBLE_DEVICES="0"
export QGANS_USE_GPU="true"

# Logging level
export QGANS_LOG_LEVEL="INFO"

Basic Configuration

Create a configuration file qgans_config.yaml:

# QGANS Pro Configuration
backend:
  default: "qiskit"
  fallback: "pennylane"

devices:
  qiskit:
    simulator: "aer_simulator"
    real: "ibmq_qasm_simulator"
  pennylane:
    simulator: "default.qubit"

training:
  default_epochs: 100
  default_batch_size: 64
  checkpoint_interval: 10

logging:
  level: "INFO"
  save_logs: true
  log_dir: "./logs"

Load configuration in Python:

from qgans_pro.config import load_config

config = load_config("qgans_config.yaml")

⚛️ Quantum Backend Configuration

Qiskit Configuration

Configure Qiskit for various use cases:

from qgans_pro.backends import QiskitBackend

# Local simulator (fastest)
backend = QiskitBackend(
    device="aer_simulator",
    shots=1024,
    optimization_level=1
)

# Real quantum hardware
backend = QiskitBackend(
    device="ibmq_qasm_simulator",
    shots=8192,
    optimization_level=3,
    hub="ibm-q",
    group="open",
    project="main"
)

# GPU-accelerated simulator
backend = QiskitBackend(
    device="aer_simulator",
    shots=4096,
    method="statevector",
    device_options={"gpu": True}
)

PennyLane Configuration

Set up PennyLane for different scenarios:

from qgans_pro.backends import PennyLaneBackend

# Default simulator
backend = PennyLaneBackend(
    device="default.qubit",
    shots=None,  # Exact simulation
    diff_method="parameter-shift"
)

# GPU-accelerated
backend = PennyLaneBackend(
    device="default.qubit",
    shots=None,
    interface="torch",
    diff_method="backprop"
)

# Lightning simulator (faster)
backend = PennyLaneBackend(
    device="lightning.qubit",
    shots=None,
    diff_method="adjoint"
)

Hybrid Configuration

Use multiple backends for hybrid approaches:

from qgans_pro import HybridGAN

# Quantum generator, classical discriminator
qgan = HybridGAN(
    generator_backend="qiskit",
    discriminator_backend="classical",
    generator_config={
        "device": "aer_simulator",
        "shots": 2048
    }
)

🏗️ Model Architecture Configuration

Circuit Architecture

Configure quantum circuit architectures:

# Variational Quantum Eigensolver (VQE) style
generator_config = {
    "n_qubits": 8,
    "n_layers": 3,
    "entanglement": "full",
    "rotation_gates": ["rx", "ry", "rz"],
    "entangling_gate": "cx",
    "parameter_initialization": "random"
}

# Quantum Approximate Optimization Algorithm (QAOA) style
generator_config = {
    "n_qubits": 6,
    "n_layers": 2,
    "entanglement": "linear",
    "rotation_gates": ["ry"],
    "entangling_gate": "cz",
    "parameter_initialization": "zeros"
}

# Hardware-efficient ansatz
generator_config = {
    "n_qubits": 10,
    "n_layers": 4,
    "entanglement": "circular",
    "rotation_gates": ["ry", "rz"],
    "entangling_gate": "cx",
    "parameter_initialization": "normal"
}

Model Size Guidelines

Choose appropriate model sizes:

Use Case Qubits Layers Parameters Training Time
Quick Test 4-6 2-3 ~50-100 Minutes
Research 8-10 3-4 ~200-400 Hours
Production 12-16 4-6 ~500-1000 Days 
# Quick prototyping
small_config = {
    "n_qubits": 4,
    "n_layers": 2,
    "entanglement": "linear"
}

# Research experiments
medium_config = {
    "n_qubits": 8,
    "n_layers": 3,
    "entanglement": "full"
}

# Production deployment
large_config = {
    "n_qubits": 12,
    "n_layers": 4,
    "entanglement": "full"
}

🏋️ Training Configuration

Learning Rate Schedules

Configure adaptive learning rates:

from torch.optim.lr_scheduler import StepLR, CosineAnnealingLR

# Step decay
training_config = {
    "lr_g": 0.001,
    "lr_d": 0.001,
    "scheduler": "step",
    "step_size": 30,
    "gamma": 0.5
}

# Cosine annealing
training_config = {
    "lr_g": 0.002,
    "lr_d": 0.002,
    "scheduler": "cosine",
    "T_max": 100,
    "eta_min": 1e-6
}

# Custom scheduler
def custom_lr_lambda(epoch):
    if epoch < 50:
        return 1.0
    elif epoch < 100:
        return 0.5
    else:
        return 0.1

training_config = {
    "lr_g": 0.001,
    "lr_d": 0.001,
    "scheduler": "lambda",
    "lr_lambda": custom_lr_lambda
}

Loss Function Configuration

Configure quantum-aware loss functions:

from qgans_pro.losses import QuantumWassersteinLoss, QuantumHingeLoss

# Wasserstein loss with quantum regularization
loss_config = {
    "generator_loss": QuantumWassersteinLoss(
        lambda_quantum=0.1,
        regularization_type="entanglement"
    ),
    "discriminator_loss": QuantumWassersteinLoss(
        lambda_quantum=0.05,
        gradient_penalty=10.0
    )
}

# Hinge loss for better stability
loss_config = {
    "generator_loss": QuantumHingeLoss(
        lambda_quantum=0.2,
        circuit_complexity_penalty=0.01
    ),
    "discriminator_loss": QuantumHingeLoss(
        lambda_quantum=0.1
    )
}

Advanced Training Options

Configure advanced training features:

advanced_config = {
    # Gradient accumulation
    "accumulation_steps": 4,

    # Mixed precision training
    "use_amp": True,
    "amp_opt_level": "O1",

    # Progressive growing
    "progressive_qubits": True,
    "qubit_schedule": [4, 6, 8, 10],

    # Spectral normalization
    "spectral_norm": True,
    "spectral_norm_target": "discriminator",

    # Self-attention
    "self_attention": True,
    "attention_layers": [2, 4],

    # Quantum noise
    "quantum_noise": {
        "depolarizing": 0.01,
        "amplitude_damping": 0.005,
        "phase_damping": 0.005
    }
}

💾 Data Configuration

Dataset Configuration

Configure data loading and preprocessing:

data_config = {
    "dataset": "fashion-mnist",
    "batch_size": 64,
    "shuffle": True,
    "num_workers": 4,
    "pin_memory": True,

    # Preprocessing
    "normalize": True,
    "normalization_range": (-1, 1),
    "augmentation": {
        "horizontal_flip": 0.5,
        "rotation": 10,
        "noise_std": 0.01
    },

    # Quantum preprocessing
    "quantum_encoding": "amplitude",
    "quantum_normalization": True,
    "entanglement_preprocessing": False
}

Custom Dataset Configuration

Configure custom datasets:

from qgans_pro.utils import CustomDataLoader

custom_config = {
    "data_path": "/path/to/custom/data",
    "file_format": "csv",  # or "npy", "h5", "json"
    "features": ["feature1", "feature2", "feature3"],
    "target_column": "target",

    # Preprocessing
    "scaling": "standard",  # or "minmax", "robust"
    "encoding": {
        "categorical": "onehot",
        "ordinal": "label"
    },

    # Quantum-specific
    "quantum_feature_map": "amplitude",
    "qubit_allocation": "balanced"
}

🔧 Hardware Configuration

GPU Configuration

Optimize for GPU usage:

import torch

# Single GPU
gpu_config = {
    "device": "cuda:0",
    "memory_efficient": True,
    "mixed_precision": True,
    "gradient_checkpointing": True
}

# Multi-GPU
multigpu_config = {
    "device": "cuda",
    "data_parallel": True,
    "devices": [0, 1, 2, 3],
    "master_device": 0,
    "sync_bn": True
}

# Memory optimization
memory_config = {
    "max_memory_cached": 0.8,  # 80% of GPU memory
    "empty_cache_interval": 10,  # Every 10 batches
    "pin_memory": True,
    "non_blocking": True
}

CPU Configuration

Optimize for CPU-only training:

cpu_config = {
    "num_threads": 8,
    "use_mkl": True,
    "mkl_num_threads": 4,
    "omp_num_threads": 8,
    "parallel_backend": "threading"
}

# Set in Python
torch.set_num_threads(8)
torch.set_num_interop_threads(4)

Cluster Configuration

Configure for distributed training:

distributed_config = {
    "world_size": 4,
    "rank": 0,
    "dist_url": "tcp://localhost:12355",
    "backend": "nccl",  # or "gloo" for CPU
    "find_unused_parameters": True
}

# Initialize distributed training
import torch.distributed as dist
dist.init_process_group(**distributed_config)

📊 Monitoring Configuration

Logging Configuration

Set up comprehensive logging:

import logging
from qgans_pro.utils import QGANSLogger

logging_config = {
    "level": logging.INFO,
    "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
    "handlers": [
        {
            "type": "file",
            "filename": "qgans_training.log",
            "rotation": "1 GB"
        },
        {
            "type": "tensorboard",
            "log_dir": "./tensorboard_logs"
        },
        {
            "type": "wandb",
            "project": "quantum-gans",
            "entity": "your-username"
        }
    ]
}

Metrics Configuration

Configure evaluation metrics:

metrics_config = {
    "calculate_fid": True,
    "fid_interval": 10,
    "fid_samples": 5000,

    "calculate_is": True,
    "is_interval": 10,
    "is_splits": 10,

    "quantum_metrics": {
        "fidelity": True,
        "entanglement": True,
        "coherence": True,
        "quantum_volume": False
    },

    "save_samples": True,
    "sample_interval": 5,
    "num_samples": 64
}

🔐 Security Configuration

API Keys and Credentials

Secure configuration for quantum cloud services:

# IBM Quantum
ibm_config = {
    "token": os.getenv("IBM_QUANTUM_TOKEN"),
    "hub": "ibm-q",
    "group": "open",
    "project": "main",
    "verify_ssl": True
}

# IonQ
ionq_config = {
    "api_key": os.getenv("IONQ_API_KEY"),
    "backend": "ionq_simulator",
    "timeout": 300
}

# Rigetti
rigetti_config = {
    "api_key": os.getenv("RIGETTI_API_KEY"),
    "endpoint": "https://api.rigetti.com",
    "forest_url": os.getenv("FOREST_SERVER_URL")
}

Data Privacy

Configure privacy-preserving options:

privacy_config = {
    "differential_privacy": {
        "enabled": True,
        "epsilon": 1.0,
        "delta": 1e-5,
        "mechanism": "gaussian"
    },

    "federated_learning": {
        "enabled": False,
        "aggregation": "fedavg",
        "local_epochs": 5
    },

    "homomorphic_encryption": {
        "enabled": False,
        "scheme": "ckks",
        "precision": 40
    }
}

📋 Configuration Templates

Research Template

# research_config.yaml
project:
  name: "quantum-gan-research"
  description: "Research experiments with quantum GANs"

model:
  generator:
    n_qubits: 8
    n_layers: 3
    backend: "qiskit"
    device: "aer_simulator"

  discriminator:
    n_qubits: 8
    n_layers: 3
    backend: "qiskit" 
    device: "aer_simulator"

training:
  epochs: 200
  batch_size: 32
  lr_g: 0.0002
  lr_d: 0.0002

evaluation:
  metrics: ["fid", "is", "quantum_fidelity"]
  interval: 20

logging:
  tensorboard: true
  wandb: true
  save_checkpoints: true

Production Template

# production_config.yaml
project:
  name: "quantum-gan-production"
  description: "Production deployment configuration"

model:
  generator:
    n_qubits: 12
    n_layers: 4
    backend: "pennylane"
    device: "lightning.qubit"

training:
  epochs: 500
  batch_size: 128
  lr_g: 0.0001
  lr_d: 0.0001
  mixed_precision: true

deployment:
  model_serving: true
  api_endpoint: "/generate"
  max_requests_per_minute: 100

monitoring:
  health_checks: true
  performance_metrics: true
  error_tracking: true

🛠️ Configuration Best Practices

Performance Optimization

  1. Start Small: Begin with 4-6 qubits and 2-3 layers
  2. Use GPU: Enable CUDA for faster training
  3. Batch Processing: Use appropriate batch sizes (32-128)
  4. Mixed Precision: Enable for memory efficiency
  5. Gradient Accumulation: For large effective batch sizes

Quantum-Specific Tips

  1. Circuit Depth: Keep circuits shallow to reduce noise
  2. Entanglement: Use appropriate entanglement patterns
  3. Shots: Balance accuracy vs. speed (1024-8192 shots)
  4. Noise Models: Include realistic noise for hardware
  5. Error Mitigation: Use error correction techniques

Debugging Configuration

debug_config = {
    "verbose": True,
    "save_intermediate": True,
    "profile_memory": True,
    "profile_time": True,
    "validate_gradients": True,
    "check_quantum_states": True,
    "log_circuit_depth": True
}

Configuration Management

Use configuration files instead of hardcoding parameters. This makes experiments reproducible and easier to manage.

Resource Limits

Monitor quantum circuit complexity. Circuits with >15 qubits or >5 layers may require significant computational resources.

Cloud Resources

When using cloud quantum computers, consider cost and queue times. Start with simulators and move to hardware when needed.