qbalance documentation

qbalance is a workflow toolkit for balancing quantum compilation, noise-suppression, and error-mitigation strategy choices over datasets of Qiskit circuits.

Documentation map

• Getting started: installation, a minimal Python workflow, and the equivalent CLI flow.

• Strategy configuration: StrategySpec fields, validation rules, default candidates, and JSON strategy files.

• CLI guide: command-by-command reference for dataset, adjust, matrix, report, plugins, and compile.

• Artifacts and reports: dataset layouts, balanced workload outputs, matrix JSON, and report generation.

• API reference: every public name, with its validation rules, the formulas it computes, and runnable examples with their outputs.

User guide

• Getting started
  • Install
  • Python quickstart
  • CLI quickstart
  • Use a custom strategy file
• Strategy configuration
  • Fields
  • Default candidate generation
  • Explicit strategy sets
  • Strategy JSON formats
• CLI guide
  • dataset
  • adjust
  • matrix
  • report
  • plugins
  • compile
• Artifacts and reports
  • Dataset layout
  • Balanced workload output
  • Matrix JSON
  • Reports
• API reference
  • Reading the examples
  • Package root (qbalance)
  • Datasets (qbalance.dataset)
  • Strategies (qbalance.strategies)
  • Objectives (qbalance.objectives)
  • Workflow (qbalance.workflow)
  • Benchmarking (qbalance.benchmarking)
  • Search (qbalance.search)
  • Transpilation (qbalance.transpile)
  • Metrics (qbalance.metrics)
  • Execution (qbalance.execution)
  • Mitigation (qbalance.mitigation)
  • Circuit cutting (qbalance.cutting)
  • Diagnostics (qbalance.diagnostics)
  • Backends (qbalance.backends)
  • Reports (qbalance.reports)
  • Compile cache (qbalance.cache)
  • Utilities (qbalance.utils)
  • Logging (qbalance.logging)
  • Errors (qbalance.errors)
  • Command line (qbalance.cli)

Citation

If you use qbalance in work, please cite the project metadata in CITATION.cff. The accompanying paper is available on arXiv: QBalance: A Reproducible Multi-Objective Workflow for Quantum Compilation, Noise Suppression, and Error-Mitigation Strategy Selection (DOI: 10.48550/arXiv.2605.02966).

Core flow

CircuitDataset
  -> Workload.from_dataset(...) or Workload.from_path(...)
  -> set_target("fake:generic:5" | "aer:..." | custom plugin)
  -> adjust(...)
  -> BalancedWorkload.save(...) or BalancedWorkload.to_download(...)
  -> load_balanced_workload(...) for saved-directory reloads

For fixed cross-product experiments, use qbalance.benchmarking.run_matrix(...) or the qbalance matrix CLI command.