quoptuna 1.0.1

Fairness-aware, explainable AutoML for quantum + classical machine learning — powered by Optuna & PennyLane.

Why QuOptuna?

Training a good quantum machine-learning model today means hand-writing circuits, guessing hyperparameters, and hoping the result is trustworthy. QuOptuna runs one automated search across 21 quantum and classical classifiers, prunes hopeless configurations early, audits every model for fairness, explains the winner with SHAP, and writes the research report for you — all from a point-and-click web wizard or a single CLI command.

The framework is peer-reviewed: it is published in the IEEE Systems, Man, and Cybernetics Magazine (2026) and two IEEE conference proceedings — see Publications.

✨ Features

• 21 models, one search — 16 quantum classifiers (Data Reuploading, Circuit-Centric, IQP & Projected Quantum Kernels, Quantum Kitchen Sinks, Quantum Metric Learner, Quantum Boltzmann Machines, Tree Tensor, Quanvolutional NN, WeiNet, separable & dressed variants) alongside classical baselines (SVC, LinearSVC, MLP, Perceptron, CNN), with automatic one-vs-rest multiclass support.
• Smart optimization — Optuna TPE / random / grid samplers with ASHA & Hyperband pruning, conditional per-model search spaces, and vectorized (JAX vmap) circuit evaluation for fast trials.
• Fairness in the loop — don't just measure bias, search under it: constrained mode (feasibility threshold on disparity) or multi-objective mode (accuracy-vs-fairness Pareto front), using equal-opportunity difference, demographic-parity difference, or disparate-impact metrics via fairlearn.
• Explainability built in — SHAP bar / beeswarm / violin / heatmap / waterfall plots, ROC & PR curves, confusion matrices for every trained model.
• AI-written reports — a two-agent analyst + reviewer pipeline turns your run into a readable research report (works with OpenAI, Anthropic, and Google Gemini keys).
• 6-step web wizard — Dataset → Features → Configure → Optimize → Analyze → Report. A Next.js UI served by a FastAPI backend on a single port, with live trial monitoring and restart-safe run persistence.
• REST API & headless CLI — automate everything (/api/v1/...), or run quoptuna optimize in CI. A legacy Streamlit dashboard remains available via quoptuna run --streamlit.

📦 Installation

Requires Python 3.11 or 3.12.

# Zero-install: run the full app straight from PyPI
uvx quoptuna

# Or install into your environment
pip install quoptuna        # or: uv pip install quoptuna

🚀 Quick Start

Web UI — one command boots the bundled app (FastAPI + pre-built UI on one port, no Node.js needed) and opens your browser:

uvx quoptuna

Headless CLI — optimize a UCI dataset without touching a browser:

quoptuna optimize --uci-id 267 --trials 25 --sampler tpe

Python API — drive the search from your own code:

from quoptuna import DataPreparation, Optimizer

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")

optimizer = Optimizer(db_name="experiment", study_name="trial_1", data=data_dict)
study, best_trials = optimizer.optimize(n_trials=25)

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

📖 Documentation

Full documentation lives at quoptuna.org:

• Quickstart — first optimization in five minutes
• Samplers & pruning — TPE vs. random vs. grid, ASHA/Hyperband
• Fairness-aware search — constrained & multi-objective modes
• Tuning for speed & quality — vectorization, devices, validation splits

📄 Publications & Citation

QuOptuna is described in three peer-reviewed IEEE publications:

• E. Jose, A. C. Fong, C. S. Lai, B. Fong, L. L. Lai, "Quoptuna: Automated Optimization and Governance for Quantum Machine Learning," IEEE Systems, Man, and Cybernetics Magazine, vol. 12, no. 3, pp. 116–121, 2026. doi:10.1109/MSMC.2025.3613072
• E. Jose, A. C. Fong, "Quoptuna: An Open-Source Framework for Explainable Quantum Machine Learning," 2025 Interdisciplinary Conference on Electrics and Computer (INTCEC), pp. 1–5. doi:10.1109/INTCEC65580.2025.11256089
• E. Jose, A. C. Fong, "Design and Development of an Open-Source Toolkit for Quantum Machine Learning," 2025 IEEE Int. Conf. on Recent Advances in Systems Science and Engineering (RASSE), pp. 1–6. doi:10.1109/RASSE64831.2025.11315342

If you use QuOptuna in your research, please cite the magazine article (GitHub's Cite this repository button uses CITATION.cff):

@article{jose2026quoptuna,
  author  = {Jose, Edwin and Fong, Alvis C. and Lai, Chun Sing and Fong, Bernard and Lai, Loi Lei},
  journal = {IEEE Systems, Man, and Cybernetics Magazine},
  title   = {Quoptuna: Automated Optimization and Governance for Quantum Machine Learning},
  year    = {2026},
  volume  = {12},
  number  = {3},
  pages   = {116--121},
  doi     = {10.1109/MSMC.2025.3613072}
}

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for the dev setup and workflow, and the contributor docs for the long-form guide. Please follow our Code of Conduct.

git clone https://github.com/Qentora/quoptuna.git && cd quoptuna
uv sync                # install dependencies
uv run pytest          # run the test suite

📜 License

Apache License 2.0 — see LICENSE.

🙏 Acknowledgments

Built on the shoulders of Optuna, PennyLane, qml-benchmarks (Apache-2.0), fairlearn, SHAP, FastAPI, and Next.js. Project scaffolding from the Wolt Python Package Cookiecutter. Developed at Western Michigan University. Thanks to all contributors!