QuOptuna

QuOptuna

Bridging quantum computing and hyperparameter optimization for next-generation machine learning

---

📚 Table of Contents

• About
• Key Features
• Installation
• Quick Start
• Documentation
• Development
• Contributing
• License
• Acknowledgments

---

🌟 About

QuOptuna seamlessly integrates quantum computing capabilities with the powerful Optuna hyperparameter optimization framework. By leveraging quantum algorithms, QuOptuna enables researchers and practitioners to explore optimization landscapes more efficiently, pushing the boundaries of what's possible in machine learning and computational research.

Whether you're working with quantum machine learning models or classical algorithms, QuOptuna provides the tools you need to find optimal hyperparameters faster and more effectively.

✨ Key Features

• 🔬 Quantum-Enhanced Optimization: Specialized hyperparameter tuning algorithms designed specifically for quantum machine learning workflows
• 🎯 Hybrid Model Support: Seamlessly optimize both quantum and classical models
  • Quantum Models: Circuit-Centric Classifier, Data Reuploading Classifier, Quantum Kitchen Sinks, and more
  • Classical Models: SVC, MLP Classifier, Perceptron, and other scikit-learn compatible models
• 📊 Interactive Dashboard: Real-time visualization of optimization progress through an intuitive Streamlit interface
• 🔍 Explainable AI: Built-in interpretability tools to understand model decisions and optimization trajectories
• 🔌 Extensible Architecture: Plugin-friendly design for easy integration with custom models and optimization strategies

📦 Installation

QuOptuna requires Python 3.8 or higher. Install using your preferred package manager:

Using UV (Recommended)

uv pip install quoptuna

Using pip

pip install quoptuna

Development Installation

For contributors and developers:

git clone https://github.com/Qentora/quoptuna.git
cd quoptuna
uv pip install -e ".[dev]"

🚀 Quick Start

Get up and running in minutes with this simple example:

import quoptuna as qo

# Define your objective function
def objective(trial):
    """
    Example: Minimize a simple quadratic function
    """
    x = trial.suggest_float('x', -10, 10)
    return x ** 2

# Create and run optimization study
study = qo.create_study(direction='minimize')
study.optimize(objective, n_trials=100)

# Display results
print(f"Best value: {study.best_value}")
print(f"Best parameters: {study.best_params}")

📈 Launch Interactive Dashboard

Monitor your optimization progress in real-time:

quoptuna --start

This launches a Streamlit dashboard where you can visualize optimization history, parameter importance, and convergence patterns.

📖 Documentation

Comprehensive documentation, tutorials, and API references are available at:

https://Qentora.github.io/quoptuna

Topics covered include:

• Detailed installation guides
• Quantum algorithm integration
• Advanced optimization techniques
• Custom sampler implementation
• API reference

🛠️ Development

We welcome contributions from the community! Here's how to set up your development environment:

Prerequisites

• Python 3.8 or higher
• UV package manager (recommended) or pip
• Git

Setup Development Environment

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

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

Running Tests

# Run all tests
uv run pytest

# Run with coverage report
uv run pytest --cov=quoptuna

# Generate HTML coverage report
uv run pytest --cov=quoptuna --cov-report=html

Code Quality

Maintain code quality with our linting and type-checking tools:

# Run linter
uv run ruff check .

# Auto-fix linting issues
uv run ruff check . --fix

# Type checking
uv run mypy .

🤝 Contributing

We're excited to have you contribute to QuOptuna! Here's how you can help:

1. Fork the repository on GitHub
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and write tests
4. Commit your changes: git commit -m 'Add amazing feature'
5. Push to the branch: git push origin feature/amazing-feature
6. Open a Pull Request

Please ensure your code:

• Passes all tests (pytest)
• Follows our style guide (ruff check)
• Includes appropriate documentation
• Has type hints where applicable

For detailed guidelines, see our Contributing Guidelines.

📄 License

This project is licensed under the Apache 2.0 License. See the LICENSE file for full details.

🙏 Acknowledgments

This project builds on the excellent work of:

• Wolt Python Package Cookiecutter - Project template and structure
• XanaduAI's qml-benchmarks - Quantum machine learning benchmarking tools (Apache License 2.0)
• Optuna - The hyperparameter optimization framework that powers QuOptuna

Special thanks to all our contributors who help make QuOptuna better!

---

📊 Project Activity

/ Recent activity

---

Documentation • Report Bug • Request Feature

Made with ❤️ by the Qentora team