LEARNING_EXAMPLES.md

Quantum Geometric Learning Examples Guide

This guide explains how to use and adapt the provided quantum learning examples for your own tasks.

Overview

The library provides several example implementations of common quantum machine learning tasks:

1. Classification - Binary and multi-class quantum classification
2. Regression - Quantum-enhanced continuous value prediction
3. Autoencoder - Quantum dimensionality reduction and feature learning
4. Clustering - Quantum-enhanced unsupervised learning

Quick Start

The easiest way to get started is using our setup script:

cd examples/beginner
./setup_and_run.sh --example quantum_classification_example

Or build manually:

# Build examples
cd examples/beginner
cmake .
make

# Run examples
./quantum_classification_example
./quantum_regression_example
./quantum_autoencoder_example
./quantum_clustering_example

Using Real-World Datasets

Loading Your Data

The examples support various data formats:

// CSV files
dataset_t* data = quantum_load_dataset(
    "data.csv",
    .format = DATA_FORMAT_CSV,
    .normalize = true
);

// NumPy arrays
dataset_t* data = quantum_load_dataset(
    "data.npy",
    .format = DATA_FORMAT_NUMPY
);

// HDF5 datasets
dataset_t* data = quantum_load_dataset(
    "data.h5",
    .format = DATA_FORMAT_HDF5,
    .dataset = "features"
);

// Custom binary format
dataset_t* data = quantum_load_dataset(
    "data.bin",
    .format = DATA_FORMAT_BINARY,
    .dtype = DTYPE_FLOAT32
);

Data Preprocessing

// Normalize data
quantum_normalize_data(data, NORMALIZATION_ZSCORE);

// Handle missing values
quantum_handle_missing(data, MISSING_STRATEGY_MEAN);

// Split dataset
dataset_split_t split = quantum_split_dataset(
    data,
    .train_ratio = 0.8,
    .validation_ratio = 0.1,
    .test_ratio = 0.1,
    .shuffle = true,
    .stratify = true
);

Common Structure

All examples follow a similar structure:

1. Hardware Configuration
2. Model Creation
3. Data Preparation
4. Distributed Training Setup
5. Training and Evaluation
6. Result Visualization

Classification Example

The classification example (quantum_classification_example.c) demonstrates:

// Configure quantum hardware
quantum_hardware_config_t hw_config = {
    .backend = BACKEND_SIMULATOR,
    .num_qubits = INPUT_DIM,
    .optimization = {
        .circuit_optimization = true,
        .error_mitigation = true
    }
};

// Create and train model
quantum_model_t* model = quantum_model_create(&model_config);
training_result_t result = quantum_train_distributed(
    model, train_data, manager, &train_config, monitor
);

Adapting for your task:

• Modify INPUT_DIM for your feature dimension
• Adjust model_config architecture
• Use quantum_load_dataset() for your data
• Configure appropriate metrics

Regression Example

The regression example (quantum_regression_example.c) shows:

// Configure model for continuous output
quantum_model_config_t model_config = {
    .input_dim = INPUT_DIM,
    .output_dim = OUTPUT_DIM,
    .quantum_depth = QUANTUM_DEPTH,
    .measurement_basis = MEASUREMENT_BASIS_CONTINUOUS,
    .optimization = {
        .learning_rate = 0.001,
        .geometric_enhancement = true,
        .loss_function = LOSS_MSE
    }
};

Adapting for your task:

• Set appropriate OUTPUT_DIM
• Choose suitable loss function
• Configure error metrics
• Adjust learning parameters

Autoencoder Example

The autoencoder example (quantum_autoencoder_example.c) demonstrates:

// Configure autoencoder architecture
quantum_autoencoder_config_t model_config = {
    .input_dim = INPUT_DIM,
    .latent_dim = LATENT_DIM,
    .quantum_depth = QUANTUM_DEPTH,
    .architecture = {
        .encoder_type = ENCODER_VARIATIONAL,
        .decoder_type = DECODER_QUANTUM,
        .activation = ACTIVATION_QUANTUM_RELU
    }
};

Adapting for your task:

• Choose appropriate LATENT_DIM
• Configure encoder/decoder architecture
• Set regularization parameters
• Adjust visualization options

Clustering Example

The clustering example (quantum_clustering_example.c) shows:

// Configure clustering algorithm
quantum_clustering_config_t cluster_config = {
    .num_clusters = NUM_CLUSTERS,
    .input_dim = INPUT_DIM,
    .quantum_depth = QUANTUM_DEPTH,
    .algorithm = {
        .type = CLUSTERING_QUANTUM_KMEANS,
        .distance = DISTANCE_QUANTUM_FIDELITY,
        .initialization = INIT_QUANTUM_KMEANS_PLUS_PLUS
    }
};

Adapting for your task:

• Set appropriate NUM_CLUSTERS
• Choose distance metric
• Configure initialization method
• Adjust convergence parameters

Distributed Training

All examples support distributed training:

// Configure distributed training
distributed_config_t dist_config = {
    .world_size = size,
    .local_rank = rank,
    .batch_size = 32,
    .checkpoint_dir = "/path/to/checkpoints"
};

// Create distributed manager
distributed_manager_t* manager = distributed_manager_create(&dist_config);

Key considerations:

• Set appropriate batch size
• Configure checkpointing
• Enable error recovery
• Monitor performance

Performance Monitoring

All examples include comprehensive monitoring:

// Configure monitoring
monitoring_config_t mon_config = {
    .metrics = {
        .loss = true,
        .accuracy = true,
        .quantum_state = true
    },
    .visualization = {
        .training_progress = true,
        .quantum_states = true
    }
};

// Create monitor
monitor_t* monitor = quantum_create_monitor(&mon_config);

Error Handling

All examples implement robust error handling:

// Check results
if (result.status != SUCCESS) {
    fprintf(stderr, "Error: %s\n", result.error_message);
    // Handle error...
}

// Validate inputs
if (!quantum_validate_input(input)) {
    fprintf(stderr, "Invalid input\n");
    // Handle error...
}

Best Practices

1. Data Preparation

   • Normalize inputs appropriately
   • Validate data quality
   • Use appropriate encoding

2. Model Configuration

   • Start with simple architectures
   • Gradually increase complexity
   • Monitor quantum resources

3. Training

   • Use appropriate batch sizes
   • Enable checkpointing
   • Monitor convergence

4. Evaluation

   • Use multiple metrics
   • Validate results
   • Generate visualizations

5. Resource Management

   • Monitor memory usage
   • Track quantum operations
   • Optimize circuits

Advanced Usage

Custom Models

// Define custom model
quantum_model_config_t custom_config = {
    .architecture = {
        .type = MODEL_CUSTOM,
        .custom_circuit = your_circuit_function,
        .custom_optimizer = your_optimizer_function
    }
};

Custom Metrics

// Define custom metrics
monitoring_config_t custom_metrics = {
    .metrics = {
        .custom_metric = your_metric_function,
        .custom_visualization = your_visualization_function
    }
};

Hardware Optimization

// Configure hardware-specific optimizations
hardware_config_t hw_opt = {
    .backend = your_backend,
    .optimization = {
        .custom_optimization = your_optimization_function
    }
};

Troubleshooting

Common issues and solutions:

1. Memory Issues

   • Reduce batch size
   • Enable gradient checkpointing
   • Monitor memory usage

2. Convergence Issues

   • Adjust learning rate
   • Modify architecture
   • Check data quality

3. Performance Issues

   • Enable circuit optimization
   • Use appropriate hardware
   • Monitor resource usage

4. Distributed Issues

   • Check network configuration
   • Monitor communication
   • Enable error recovery

Further Reading

• Quantum ML Documentation
• Performance Tuning Guide
• Error Handling Guide
• Data Preparation Guide

These examples provide a starting point for implementing quantum machine learning tasks. Adapt them to your specific needs while following the provided best practices and guidelines.