Home / Project guide

Project guide

Project Guide | Quantum Workbench

Free quantum-learning lab note for explaining circuits, measurement, and experiments. This guide organizes the repository's original implementation notes for technical learners and education-content builders.

Reviewed 2026-07-28. This page is derived from checked-in repository evidence and links back to its source.

Live Demo

Curated supporting repo This repository is kept as optional proof, but it no longer leads the portfolio. Current front door: agent-orchestration-benchmark, tool-call-finetune-lab, and stage-pilot. Reason: Broad education/research tooling is less targeted than the current AI platform, governance, and ops lanes.

A web-based experiment desk for running quantum circuits across local simulators, Amazon Braket, and IBM Quantum hardware, then comparing results side by side.

System Overview

A quantum experiment desk that shows research-tool discipline: local simulation first, managed backends second.

AreaDetails
UsersResearch teams, students, technical reviewers, and cloud/quantum platform evaluators.
Technical pathValidate the demo, README, architecture notes, and quality gate before deeper workflow review.
System scopeQiskit/Braket framing, local simulation, optional managed-backend adapters, and experiment review surfaces.
Operating boundaryManaged backend use should be opt-in and budget-controlled; local simulation remains the safe default.
Evaluation pathRun the local simulation path and inspect generated experiment outputs and adapter boundaries.

Evaluation Path

Architecture Notes

What it does

Experiments

ExperimentDescription
bell_pair2-qubit Bell state - shows entanglement and hardware noise
ghz_three3-qubit GHZ state - shows multi-qubit coherence
qaoa_triangleSingle-layer QAOA Max-Cut on a triangle graph
h2_vqe_miniSmall H2 Hamiltonian with exact baseline and parameter sweep

Real hardware evidence

Historical hardware run on ibm_torino (2026-03-17). This is evidence of adapter behavior, not a public hardware-access guarantee:

Quick Start

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev]"
uvicorn app.main:app --reload

Open http://127.0.0.1:8000/

IBM Quantum (optional)

export IBM_QUANTUM_TOKEN="<your_token>"
export QUANTUM_OPERATOR_TOKEN="<operator-token-for-hardware-routes>"

Amazon Braket (optional)

export AWS_PROFILE="<your_profile>"
export AWS_DEFAULT_REGION="us-west-1"

If credentials aren't set, hardware routes are blocked and local simulation still works. If provider credentials exist but QUANTUM_OPERATOR_TOKEN is missing, hardware routes still fail closed.

API

EndpointDescription
GET /healthRuntime status
GET /api/experimentsExperiment catalog
GET /api/backendsAvailable hardware backends
GET /api/runsRun history
POST /api/runs/localRun on ideal local sampler
POST /api/runs/braket-localRun on Braket local simulator
POST /api/compare/local-backendsCompare both local stacks
POST /api/runs/hardwareOperator-token guarded IBM hardware submission
POST /api/runs/braket-hardwareOperator-token guarded Braket hardware submission
GET /api/evidence/scorecardLatest run summary
GET /api/ibm/proof-packOperator-token guarded IBM backend results and metadata

Architecture

+------------------+       +------------------+       +-------------------+
|   Browser / UI   | ----> |   FastAPI App    | ----> |  Quantum Runtime  |
|  (static files)  |       |   (main.py)      |       |   (runtime.py)    |
+------------------+       +------------------+       +-------------------+
                                   |                         |
                                   v                         v
                           +---------------+     +-----------------------+
                           |  RunStore     |     |   Experiments         |
                           | (store.py)    |     |   (experiments.py)    |
                           | JSON persist  |     |   Circuit builders    |
                           +---------------+     +-----------------------+
                                                         |
                                        +----------------+----------------+
                                        v                v                v
                                 +-----------+   +-----------+   +-----------+
                                 |  Qiskit   |   |  Braket   |   |  IBM /    |
                                 |  Local    |   |  Local    |   |  Braket   |
                                 | Simulator |   | Simulator |   | Hardware  |
                                 +-----------+   +-----------+   +-----------+

Tests

58 tests covering circuit construction, backend selection, result parsing, API contracts, chemistry workflow, and store persistence.

pytest -v

Project structure

quantum-workbench/
  app/
    main.py
    quantum/
      experiments.py
      runtime.py
      store.py
    static/
      index.html, app.js, style.css
  docs/
  scripts/
  tests/

References

Cloud + AI Architecture

Enterprise Productization

System Architecture

Service Architecture

Search And Service Surface