Skip to content

QuOptuna Documentation

Welcome to QuOptuna, a quantum-enhanced hyperparameter optimization framework that combines quantum computing with Optuna for advanced model tuning and explainable AI.

Overview

QuOptuna provides a comprehensive platform for: - 🎯 Automated hyperparameter optimization for quantum and classical ML models - 🔍 SHAP-based explainable AI with rich visualizations - 📊 UCI ML Repository integration for easy dataset access - 📝 AI-powered report generation for model analysis - 🖥️ Interactive Streamlit interface for the complete workflow

Quick Start

Installation

Install QuOptuna using UV (recommended) or pip:

# Using UV (recommended)
uv pip install quoptuna

# Using pip
pip install quoptuna

Launch the Application

Start the interactive Streamlit interface:

quoptuna --start

Or run directly with Python:

python -m quoptuna.frontend.app run

Basic Python Usage

from quoptuna import DataPreparation, Optimizer
from quoptuna.backend.utils.data_utils.data import mock_csv_data
import pandas as pd

# Load and prepare data
df = pd.read_csv("your_data.csv")
df["target"] = df["target"].replace({0: -1, 1: 1})

# Save data
file_path = mock_csv_data(df, tmp_path="data", file_name="my_data")

# Prepare for training
data_prep = DataPreparation(
    file_path=file_path,
    x_cols=[col for col in df.columns if col != "target"],
    y_col="target"
)
data_dict = data_prep.get_data(output_type="2")

# Run optimization
optimizer = Optimizer(db_name="experiment", study_name="trial_1", data=data_dict)
study, best_trials = optimizer.optimize(n_trials=100)

print(f"Best F1 Score: {best_trials[0].value:.4f}")
print(f"Best Model: {best_trials[0].params['model_type']}")

Key Features

🎯 Hyperparameter Optimization

Automated optimization using Optuna with support for: - Multiple quantum models (Data Reuploading, Circuit-Centric, Quantum Kitchen Sinks, etc.) - Classical baselines (SVC, MLP, Perceptron) - Multi-objective optimization - Parallel trial execution - Persistent storage with SQLite

🔍 Explainable AI

Comprehensive SHAP analysis with multiple visualization types: - Bar Plot: Feature importance ranking - Beeswarm Plot: Feature value impact distribution - Violin Plot: SHAP value distributions - Heatmap: Instance-level feature contributions - Waterfall Plot: Individual prediction explanations - Confusion Matrix: Model performance visualization

📊 Dataset Management

  • UCI ML Repository: Direct access to 100+ datasets
  • Custom Upload: Support for CSV files
  • Automatic Preprocessing: Handle missing values, feature scaling
  • Target Transformation: Binary classification support (-1/+1 encoding)

📝 AI-Powered Reports

Generate comprehensive analysis reports using: - Google Gemini - OpenAI GPT - Anthropic Claude

Reports include performance metrics, SHAP interpretations, and governance recommendations.

Supported Models

Quantum Models

  • Data Reuploading Classifier: Quantum circuit with data re-uploading
  • Circuit-Centric Classifier: Parameterized quantum circuits
  • Quantum Kitchen Sinks: Quantum feature maps
  • Quantum Metric Learner: Metric learning with quantum circuits
  • Dressed Quantum Circuit Classifier: Hybrid quantum-classical

Classical Models

  • Support Vector Classifier (SVC): With multiple kernels
  • Multi-Layer Perceptron (MLP): Neural network classifier
  • Perceptron: Simple linear classifier

Documentation

  • User Guide - Complete walkthrough of the Streamlit interface
  • API Reference - Detailed API documentation for Python usage
  • Examples - Code examples for common use cases
  • Changelog - Version history and updates

Workflow

QuOptuna provides a structured workflow:

  1. Dataset Selection
  2. Load from UCI ML Repository or upload CSV
  3. Configure features and target

  4. Apply preprocessing

  5. Optimization

  6. Prepare train/test splits
  7. Run hyperparameter optimization

  8. Review best performing models

  9. Model Training

  10. Select best trial
  11. Train model with optimized parameters

  12. Evaluate performance

  13. SHAP Analysis

  14. Calculate SHAP values
  15. Generate multiple visualization types

  16. Understand feature importance

  17. Report Generation

  18. Create AI-powered analysis
  19. Export results
  20. Share insights

System Requirements

  • Python 3.8+
  • 4GB+ RAM (8GB recommended for quantum models)
  • Internet connection (for UCI datasets and LLM reports)

Dependencies

Core dependencies: - optuna - Hyperparameter optimization - streamlit - Web interface - shap - Explainable AI - pennylane - Quantum computing - scikit-learn - Classical ML models - pandas, numpy - Data processing

Development

Setup

# Clone repository
git clone https://github.com/Qentora/quoptuna.git
cd quoptuna

# Install development dependencies
uv pip install -e ".[dev]"

# Run tests
uv run pytest

# Run linting
uv run ruff check .
uv run mypy .

Project Structure

quoptuna/
├── src/quoptuna/
│   ├── backend/         # Core optimization and model code
│   │   ├── models/      # Model implementations
│   │   ├── tuners/      # Optuna integration
│   │   ├── xai/         # SHAP analysis
│   │   └── utils/       # Utilities
│   └── frontend/        # Streamlit interface
│       ├── pages/       # Multi-page app
│       ├── app.py       # Main application
│       └── support.py   # Helper functions
├── docs/                # Documentation
├── experiments/         # Example notebooks
└── tests/              # Unit tests

Contributing

We welcome contributions! Please see our Contributing Guidelines.

Ways to Contribute

  • 🐛 Report bugs and issues
  • 💡 Suggest new features
  • 📝 Improve documentation
  • 🔧 Submit pull requests
  • ⭐ Star the repository

Support & Community

License

QuOptuna is released under the MIT License. See LICENSE for details.

Citation

If you use QuOptuna in your research, please cite:

@software{quoptuna,
  title = {QuOptuna: Quantum-Enhanced Machine Learning Optimization},
  author = {QuOptuna Team},
  year = {2024},
  url = {https://github.com/Qentora/quoptuna}
}

Acknowledgments

Built with: - Optuna - Hyperparameter optimization framework - PennyLane - Quantum machine learning - SHAP - Explainable AI - Streamlit - Web framework

Ready to get started? Check out the User Guide or launch the app with quoptuna --start!