QuantumLearning/README.md

# QuantumLearning

Local-first, notebook-first Qiskit learning platform for IBM-style gate-model circuit building. The main path stays fully local: no IBM cloud tokens, no live API dependency, and no IDE-specific workflow assumptions.

The original notebook set was only the bootcamp layer. The actual platform target is larger:

**train an amateur into an independent hardware-aware quantum circuit designer**

That requires a backward-designed apprenticeship, not just a forward topic list.

The teaching spine intentionally alternates between two modes:

- Ideal mode: clean circuit construction, statevectors, probabilities, and conceptual clarity.
- Reality mode: transpilation constraints, routing overhead, noisy simulation, and backend-style distortion.

The notebooks are now intentionally literature-heavy and interactive:

- long-form lecture writing inside the notebooks, not only in side documents
- multiple-choice concept checks in every technical notebook
- editable circuit labs with code markers tied to diagram-reference tables
- reflection boxes that force written explanation rather than passive reading
- rubric scorecards, evidence checklists, and revision loops in the professional band

The current rebuild direction is now explicit:

- textbook spine from the Loredo book for sequencing and coverage
- apprenticeship layer for mastery gates and professional design pressure
- `Lecture / Lab / Problems / Studio` bundles instead of one mixed notebook per topic

## Project Layout

```text
QuantumLearning/
├── scripts/
├── assets/figures/
├── configs/
├── notebooks/
├── src/
├── tests/
├── .playwright-browsers/
├── .venv/
├── pyproject.toml
└── README.md
```

## Quick Start

Use the consumer-facing control script on macOS:

```bash
cd /Users/oho/GitClone/CodexProjects/QuantumLearning
bash ./scripts/app.sh bootstrap
```

That creates `.venv/`, installs the Python dependencies, and installs the project-local Playwright Chromium runtime into `.playwright-browsers/`.

For normal consumer use, these are the only commands you should need:

```bash
bash ./scripts/app.sh start --open
bash ./scripts/app.sh status
bash ./scripts/app.sh restart
bash ./scripts/app.sh stop
bash ./scripts/app.sh reset-state
```

`bash ./scripts/app.sh start --open` always opens [START_HERE.ipynb](/Users/oho/GitClone/CodexProjects/QuantumLearning/notebooks/START_HERE.ipynb). That is the only supported first notebook. From there, the learner should follow the explicit next-notebook handoff inside each notebook instead of browsing the filesystem.

If you want a fast operational check immediately after bootstrap:

```bash
bash ./scripts/app.sh status
bash ./scripts/app.sh validate --quick
```

The app command starts Jupyter as a detached background service, prints the exact URL, cleans up stale runtime files when needed, and writes logs to `.logs/jupyterlab.log`.

```bash
bash ./scripts/app.sh start
```

If the server is already running, the same command returns the current URL instead of starting a duplicate server.

If you want a different local port:

```bash
bash ./scripts/app.sh start --port 8890
```

If you want to restart the whole Jupyter layer cleanly:

```bash
bash ./scripts/app.sh restart
```

If you want to inspect the live log:

```bash
bash ./scripts/app.sh logs -f
```

If JupyterLab reopens old tabs, looks like notebooks are still running, or you want a true clean slate for the repo-local Jupyter state:

```bash
bash ./scripts/app.sh reset-state
```

Run the tests:

```bash
bash ./scripts/app.sh validate --standard
```

Run the measured local coverage report:

```bash
bash ./scripts/app.sh validate --full
```

On a normal Mac terminal, the full validation path runs the browser and notebook execution suites as well. In restricted automation sandboxes, those suites may skip because localhost kernel or browser ports are blocked.

If you deliberately skipped the local browser runtime during bootstrap, install it later with:

```bash
source .venv/bin/activate
PLAYWRIGHT_BROWSERS_PATH="$PWD/.playwright-browsers" python -m playwright install chromium
```

## Curriculum Backbone

The didactical concept is documented in [MASTERY_MODEL.md](/Users/oho/GitClone/CodexProjects/QuantumLearning/MASTERY_MODEL.md).
The assessment and competence model is documented in [configs/assessment_blueprint.toml](/Users/oho/GitClone/CodexProjects/QuantumLearning/configs/assessment_blueprint.toml).

The rebuilt course is now organized into five bands:

1. Orientation
2. Foundations
3. Qiskit Engineering
4. Algorithmic Design
5. Professional Design

The consumer entry point is [START_HERE.ipynb](/Users/oho/GitClone/CodexProjects/QuantumLearning/notebooks/START_HERE.ipynb).
The first serious orientation notebook after that is [COURSE_BLUEPRINT.ipynb](/Users/oho/GitClone/CodexProjects/QuantumLearning/notebooks/COURSE_BLUEPRINT.ipynb).
The consumer route is intentionally single-path. Follow the notebook handoff from `START_HERE` to `COURSE_COMPLETE` without branching into side material.
The cell contract is now explicit:

- `META` cells are course-structure, pacing, objectives, or navigation
- `MANDATORY` cells are the official walkthrough
- `FACULTATIVE` cells are optional extensions only
- difficulty `1-3` is reserved for mandatory cells
- difficulty `4-10` is reserved for facultative cells
- `START_HERE`, `COURSE_BLUEPRINT`, and `COURSE_COMPLETE` are route notebooks, so they do not contain facultative extensions

The full `Foundations` band is now rebuilt as module bundles:

- [Module 1: Principles and Circuit Literacy](</Users/oho/GitClone/CodexProjects/QuantumLearning/notebooks/foundations/module_01_principles_and_circuit_literacy>)
- [Module 2: Qubit and Statevector Intuition](</Users/oho/GitClone/CodexProjects/QuantumLearning/notebooks/foundations/module_02_qubit_and_statevector_intuition>)
- [Module 3: Gates and Measurement](</Users/oho/GitClone/CodexProjects/QuantumLearning/notebooks/foundations/module_03_gates_and_measurement>)

The `Qiskit Engineering` band is also rebuilt:

- [Module 4: Circuit Construction and Analysis](</Users/oho/GitClone/CodexProjects/QuantumLearning/notebooks/qiskit_engineering/module_01_circuit_construction_and_analysis>)
- [Module 5: Transpilation and Visualization](</Users/oho/GitClone/CodexProjects/QuantumLearning/notebooks/qiskit_engineering/module_02_transpilation_and_visualization>)
- [Module 6: Simulation and Noise Models](</Users/oho/GitClone/CodexProjects/QuantumLearning/notebooks/qiskit_engineering/module_03_simulation_and_noise_models>)

The `Algorithmic Design` band is now rebuilt too:

- [Module 7: Deutsch Family and Oracle Thinking](</Users/oho/GitClone/CodexProjects/QuantumLearning/notebooks/algorithms/module_01_deutsch_family>)
- [Module 8: Bernstein-Vazirani and Structured Oracles](</Users/oho/GitClone/CodexProjects/QuantumLearning/notebooks/algorithms/module_02_bernstein_vazirani>)
- [Module 9: QFT and Periodic Structure](</Users/oho/GitClone/CodexProjects/QuantumLearning/notebooks/algorithms/module_03_qft>)
- [Module 10: Grover and Amplitude Amplification](</Users/oho/GitClone/CodexProjects/QuantumLearning/notebooks/algorithms/module_04_grover>)

The `Professional Design` band is now rebuilt as well:

- [Module 11: Qiskit Patterns and Workflow Design](</Users/oho/GitClone/CodexProjects/QuantumLearning/notebooks/professional/module_01_qiskit_patterns>)
- [Module 12: Hardware-Aware Redesign Studio](</Users/oho/GitClone/CodexProjects/QuantumLearning/notebooks/professional/module_02_hardware_aware_redesign>)
- [Module 13: Noise-Aware Verification and Mitigation](</Users/oho/GitClone/CodexProjects/QuantumLearning/notebooks/professional/module_03_noise_aware_verification>)
- [Module 14: Capstone Circuit Design Review](</Users/oho/GitClone/CodexProjects/QuantumLearning/notebooks/professional/module_04_capstone_design_review>)

The old single-notebook sequence is no longer part of the visible learner path. The canonical course path is the guarded `START_HERE -> COURSE_BLUEPRINT -> bundle mainline -> COURSE_COMPLETE` route.
There is no second supported walkthrough.

See [FIRST_RUN.md](/Users/oho/GitClone/CodexProjects/QuantumLearning/FIRST_RUN.md) for the short startup checklist.
See [OPERATIONS.md](/Users/oho/GitClone/CodexProjects/QuantumLearning/OPERATIONS.md) for setup on another Mac, monitoring, validation, and recovery.
See [AGENT_CONTEXT.md](/Users/oho/GitClone/CodexProjects/QuantumLearning/AGENT_CONTEXT.md) and [AGENT_RESTART_PROTOCOL.md](/Users/oho/GitClone/CodexProjects/QuantumLearning/AGENT_RESTART_PROTOCOL.md) for fast agent restart handoff.

The lower-level scripts still exist:
- `scripts/bootstrap_mac.sh`
- `scripts/start_jupyter.sh`
- `scripts/project_status.sh`
- `scripts/run_validation.sh`

Those are now plumbing. `scripts/app.sh` is the consumer entrypoint.

## Local-First Design Rules

- Main workflow uses local simulators only.
- No IBM token is required.
- Transpilation examples use local constraints and simulator-compatible backends.
- Circuit graphics are first-class and rely on local `matplotlib`, `pylatexenc`, and `Pillow`.
- The browser validation stack uses a repo-local Playwright runtime in `.playwright-browsers/`.