Skip to content

Losses API Reference

This module contains specialized loss functions designed for quantum GANs, including quantum-aware variants of classical GAN losses.

Quantum Loss Functions

QuantumWassersteinLoss

Quantum-enhanced Wasserstein loss with gradient penalty and quantum regularization.

class QuantumWassersteinLoss(nn.Module):
    """
    Quantum-enhanced Wasserstein loss function.

    Extends the classical Wasserstein loss with quantum-specific
    regularization terms to improve training stability and leverage
    quantum advantages.
    """

Constructor

def __init__(
    self,
    lambda_gp: float = 10.0,
    lambda_quantum: float = 1.0,
    quantum_regularization: bool = True,
    entanglement_penalty: float = 0.1,
    device: str = "cpu"
):

Parameters:

  • lambda_gp: Gradient penalty coefficient
  • lambda_quantum: Quantum regularization weight
  • quantum_regularization: Enable quantum-specific regularization
  • entanglement_penalty: Penalty for excessive entanglement
  • device: Device for computation

Usage Examples

from qgans_pro.losses import QuantumWassersteinLoss
import torch

# Initialize quantum Wasserstein loss
loss_fn = QuantumWassersteinLoss(
    lambda_gp=10.0,
    lambda_quantum=1.0,
    quantum_regularization=True
)

# Use in training loop
def train_step(real_data, generator, discriminator):
    # Generate fake data
    fake_data = generator(noise)

    # Compute discriminator scores
    real_scores = discriminator(real_data)
    fake_scores = discriminator(fake_data)

    # Compute loss
    d_loss = loss_fn.discriminator_loss(
        real_scores=real_scores,
        fake_scores=fake_scores,
        real_data=real_data,
        fake_data=fake_data,
        discriminator=discriminator
    )

    g_loss = loss_fn.generator_loss(fake_scores)

    return d_loss, g_loss

Methods

discriminator_loss(real_scores, fake_scores, real_data, fake_data, discriminator)

Compute discriminator loss with gradient penalty.

Parameters:

  • real_scores: Discriminator scores for real data
  • fake_scores: Discriminator scores for fake data
  • real_data: Real training data
  • fake_data: Generated fake data
  • discriminator: Discriminator model

Returns:

  • torch.Tensor: Discriminator loss
generator_loss(fake_scores, quantum_states=None)

Compute generator loss with optional quantum regularization.

Parameters:

  • fake_scores: Discriminator scores for fake data
  • quantum_states: Optional quantum states for regularization

Returns:

  • torch.Tensor: Generator loss
gradient_penalty(real_data, fake_data, discriminator)

Compute gradient penalty for WGAN-GP.

Parameters:

  • real_data: Real training data
  • fake_data: Generated fake data
  • discriminator: Discriminator model

Returns:

  • torch.Tensor: Gradient penalty term

QuantumHingeLoss

Quantum-aware hinge loss for adversarial training.

class QuantumHingeLoss(nn.Module):
    """
    Quantum-enhanced hinge loss function.

    Adapts the hinge loss for quantum GANs with quantum-aware
    margin scaling and entanglement regularization.
    """

Usage Examples

from qgans_pro.losses import QuantumHingeLoss

# Initialize quantum hinge loss
hinge_loss = QuantumHingeLoss(
    margin=1.0,
    quantum_margin_scaling=True,
    entanglement_regularization=True
)

# Use in training
d_loss = hinge_loss.discriminator_loss(real_scores, fake_scores)
g_loss = hinge_loss.generator_loss(fake_scores)

QuantumLSGANLoss

Least squares loss adapted for quantum GANs.

class QuantumLSGANLoss(nn.Module):
    """
    Quantum-enhanced least squares GAN loss.

    Provides stable training for quantum GANs with quantum
    state regularization and fidelity preservation.
    """

Usage Examples

from qgans_pro.losses import QuantumLSGANLoss

# Initialize LSGAN loss with quantum enhancements
lsgan_loss = QuantumLSGANLoss(
    real_label=1.0,
    fake_label=0.0,
    quantum_fidelity_weight=0.5
)

# Compute losses
d_loss = lsgan_loss.discriminator_loss(real_scores, fake_scores)
g_loss = lsgan_loss.generator_loss(fake_scores)

Quantum Regularization Terms

QuantumFidelityLoss

Preserve quantum fidelity during generation.

class QuantumFidelityLoss(nn.Module):
    """
    Quantum fidelity preservation loss.

    Encourages the generator to maintain quantum fidelity
    between input quantum states and generated outputs.
    """

Usage Examples

from qgans_pro.losses import QuantumFidelityLoss

# Initialize fidelity loss
fidelity_loss = QuantumFidelityLoss(
    target_fidelity=0.95,
    measurement_shots=1024
)

# Add to generator loss
quantum_loss = fidelity_loss(
    input_states=input_quantum_states,
    output_states=generated_quantum_states
)

total_generator_loss = adversarial_loss + 0.1 * quantum_loss

EntanglementRegularization

Control entanglement in quantum circuits.

class EntanglementRegularization(nn.Module):
    """
    Entanglement regularization for quantum circuits.

    Provides control over the amount of entanglement in
    quantum circuits to balance expressivity and trainability.
    """

Usage Examples

from qgans_pro.losses import EntanglementRegularization

# Initialize entanglement regularization
entanglement_reg = EntanglementRegularization(
    target_entanglement=0.7,
    regularization_strength=0.01
)

# Apply to quantum generator
ent_loss = entanglement_reg(generator.get_quantum_states())
total_loss = gan_loss + ent_loss

Advanced Loss Functions

QuantumFeatureMatchingLoss

Feature matching loss for quantum generators.

class QuantumFeatureMatchingLoss(nn.Module):
    """
    Quantum feature matching loss.

    Matches features between real and generated data in both
    classical feature space and quantum feature space.
    """

Usage Examples

from qgans_pro.losses import QuantumFeatureMatchingLoss

# Initialize feature matching loss
fm_loss = QuantumFeatureMatchingLoss(
    feature_layers=['conv1', 'conv2', 'quantum_layer'],
    quantum_feature_weight=0.5
)

# Use with discriminator features
feature_loss = fm_loss(
    real_features=discriminator.extract_features(real_data),
    fake_features=discriminator.extract_features(fake_data)
)

QuantumPerceptualLoss

Perceptual loss using quantum feature extractors.

class QuantumPerceptualLoss(nn.Module):
    """
    Quantum perceptual loss.

    Uses quantum feature extractors to compute perceptual
    differences between real and generated data.
    """

Usage Examples

from qgans_pro.losses import QuantumPerceptualLoss

# Initialize perceptual loss
perceptual_loss = QuantumPerceptualLoss(
    feature_extractor='quantum_vgg',
    layers=['block1', 'block2', 'quantum_block'],
    weights=[1.0, 0.5, 0.3]
)

# Compute perceptual similarity
perc_loss = perceptual_loss(real_images, generated_images)

Loss Combiners and Schedulers

AdaptiveLossWeighting

Automatically balance multiple loss terms.

class AdaptiveLossWeighting(nn.Module):
    """
    Adaptive loss weighting for multi-objective training.

    Automatically adjusts weights of different loss components
    based on training dynamics and quantum circuit properties.
    """

Usage Examples

from qgans_pro.losses import AdaptiveLossWeighting

# Initialize adaptive weighting
adaptive_weights = AdaptiveLossWeighting(
    loss_names=['adversarial', 'quantum_fidelity', 'entanglement'],
    adaptation_method='gradient_based',
    update_frequency=100
)

# Use in training loop
losses = {
    'adversarial': adversarial_loss,
    'quantum_fidelity': fidelity_loss,
    'entanglement': entanglement_loss
}

weighted_loss = adaptive_weights(losses, epoch=current_epoch)

QuantumLossScheduler

Schedule loss weights based on quantum training dynamics.

class QuantumLossScheduler:
    """
    Schedule loss weights during quantum GAN training.

    Adjusts loss component weights based on quantum circuit
    training progress and stability metrics.
    """

Usage Examples

from qgans_pro.losses import QuantumLossScheduler

# Initialize loss scheduler
scheduler = QuantumLossScheduler(
    schedule_type='quantum_aware',
    warmup_epochs=10,
    quantum_focus_epochs=50
)

# Update weights during training
for epoch in range(epochs):
    weights = scheduler.get_weights(
        epoch=epoch,
        quantum_metrics=quantum_metrics,
        training_stability=stability_score
    )

    total_loss = (
        weights['adversarial'] * adversarial_loss +
        weights['quantum'] * quantum_loss +
        weights['regularization'] * reg_loss
    )

Quantum-Classical Hybrid Losses

HybridGANLoss

Specialized loss for hybrid quantum-classical GANs.

class HybridGANLoss(nn.Module):
    """
    Loss function for hybrid quantum-classical GANs.

    Balances quantum and classical components in hybrid
    generator-discriminator architectures.
    """

Usage Examples

from qgans_pro.losses import HybridGANLoss

# Initialize hybrid loss
hybrid_loss = HybridGANLoss(
    quantum_weight=0.6,
    classical_weight=0.4,
    interaction_weight=0.2,
    loss_type='wasserstein'
)

# Use with hybrid models
total_loss = hybrid_loss(
    quantum_generator=quantum_gen,
    classical_discriminator=classical_disc,
    real_data=real_data,
    noise=noise
)

Utility Functions

Loss Analysis and Visualization

Tools for analyzing and visualizing loss behavior:

from qgans_pro.losses.utils import LossAnalyzer, LossVisualizer

# Analyze loss behavior
analyzer = LossAnalyzer()
analysis = analyzer.analyze_loss_landscape(
    generator=generator,
    discriminator=discriminator,
    loss_fn=loss_function,
    data_sample=sample_batch
)

# Visualize loss components
visualizer = LossVisualizer()
visualizer.plot_loss_components(
    loss_history=training_history,
    save_path='loss_analysis.png'
)

# Create loss landscape visualization
visualizer.plot_loss_landscape_3d(
    analysis=analysis,
    save_path='loss_landscape.png'
)

Loss Function Factory

Create loss functions with predefined configurations:

from qgans_pro.losses import create_loss_function

# Create loss with preset configuration
loss_fn = create_loss_function(
    loss_type='quantum_wasserstein',
    preset='stable',  # 'stable', 'aggressive', 'research'
    quantum_weight=1.0
)

# Create custom loss combination
custom_loss = create_loss_function(
    loss_type='hybrid',
    components={
        'adversarial': {'type': 'wasserstein', 'weight': 1.0},
        'quantum': {'type': 'fidelity', 'weight': 0.5},
        'regularization': {'type': 'entanglement', 'weight': 0.1}
    }
)

Best Practices

Loss Function Selection

Guidelines for choosing appropriate loss functions:

# For stable training (recommended for beginners)
stable_config = {
    'loss_type': 'quantum_wasserstein',
    'lambda_gp': 10.0,
    'lambda_quantum': 0.5,
    'quantum_regularization': True
}

# For high-quality generation (research)
quality_config = {
    'loss_type': 'quantum_feature_matching',
    'perceptual_weight': 1.0,
    'quantum_fidelity_weight': 0.8,
    'entanglement_regularization': True
}

# For fast training (prototyping)
fast_config = {
    'loss_type': 'quantum_lsgan',
    'quantum_regularization': False,
    'simple_quantum_terms': True
}

Hyperparameter Tuning

Optimize loss function parameters:

from qgans_pro.losses.tuning import LossHyperparameterTuner

# Automated hyperparameter tuning
tuner = LossHyperparameterTuner(
    loss_type='quantum_wasserstein',
    search_space={
        'lambda_gp': (1.0, 50.0),
        'lambda_quantum': (0.1, 2.0),
        'entanglement_penalty': (0.01, 1.0)
    }
)

best_params = tuner.optimize(
    generator=generator,
    discriminator=discriminator,
    dataloader=dataloader,
    epochs=20,
    metric='fid_score'
)

Common Pitfalls

Avoid these common mistakes:

# ✅ Good: Balanced loss weights
loss_fn = QuantumWassersteinLoss(
    lambda_gp=10.0,
    lambda_quantum=1.0  # Reasonable quantum weight
)

# ❌ Bad: Overwhelming quantum loss
loss_fn = QuantumWassersteinLoss(
    lambda_gp=10.0,
    lambda_quantum=100.0  # Too high, dominates training
)

# ✅ Good: Gradual introduction of quantum terms
scheduler = QuantumLossScheduler(warmup_epochs=10)

# ❌ Bad: All quantum terms from epoch 0
# Can cause training instability