quoptuna 0.0.5

quoptuna is a proposed open-source project that combines quantum computing with Optuna's hyperparameter optimization framework.

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.11 or 3.12. 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 the Application

QuOptuna ships a single command that boots the full stack (FastAPI backend + Next.js frontend) in production mode, greeting you with a gradient ASCII banner:

uv run quoptuna run

This builds the frontend, starts both services on the first free ports (defaulting to :8000 for the API and :3000 for the UI), waits until the UI is ready, prints the access links, and opens your browser automatically.

Common options:

# Pick explicit ports and skip auto-opening the browser
uv run quoptuna run --backend-port 8001 --frontend-port 3001 --no-browser

# Launch the legacy Streamlit dashboard instead of the full stack
uv run quoptuna run --streamlit

Running uv run quoptuna with no subcommand is equivalent to uv run quoptuna run. Build and server logs are streamed to files under ${TMPDIR}/quoptuna/, whose paths are printed beneath the banner.

📖 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.11 or 3.12
• UV package manager (recommended) or pip
• Node.js 18+ (for the Next.js frontend)
• 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