quoptuna 0.1.3

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. QuOptuna searches quantum and classical classifiers for you — you provide data, it finds the best model and hyperparameters:

from quoptuna import DataPreparation, Optimizer

# Load and prepare a CSV (binary targets use the {-1, +1} convention)
data_prep = DataPreparation(
    file_path="your_data.csv",
    x_cols=["feature_1", "feature_2", "feature_3"],
    y_col="target",
)
data_dict = data_prep.get_data(output_type="2")

# Run the hyperparameter search across quantum + classical models
optimizer = Optimizer(db_name="experiment", study_name="trial_1", data=data_dict)
study, best_trials = optimizer.optimize(n_trials=100)

# Display results
print(f"Best F1 score: {best_trials[0].value:.4f}")
print(f"Best model:    {best_trials[0].params['model_type']}")

🖥️ Launch the Application

QuOptuna bundles a pre-built web UI inside the Python package, so a single command boots the whole app — no Node.js, no repository checkout, just Python:

# Run straight from PyPI without installing anything permanently
uvx quoptuna

# ...or, in a project/venv that already has quoptuna installed
uv run quoptuna run

This starts one FastAPI/uvicorn process that serves both the JSON API and the bundled UI on a single port (defaulting to :8000, auto-incrementing if busy), greets you with a gradient ASCII banner, and opens your browser automatically.

URL	What
http://localhost:8000	Web UI
http://localhost:8000/api/v1/...	JSON API
http://localhost:8000/api/docs	Interactive API docs

Common options:

# Pick an explicit port and skip auto-opening the browser
uv run quoptuna run --port 8001 --no-browser

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

Running uv run quoptuna (or uvx quoptuna) with no subcommand is equivalent to uv run quoptuna run.

Dev vs packaged. The command above is the packaged mode (one process, one port, served from the wheel). For frontend development with hot reload, use the dev mode — two processes — via make run_cli (Next.js dev server on :3000 + FastAPI on :8000). See the docs for details.

📖 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+ — only for frontend development; the published package ships a pre-built UI, so running QuOptuna does not require Node
• 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