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
```

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 and Apprenticeship
2. Foundations
3. Qiskit Engineering
4. Algorithmic Design
5. Professional Design

The new entry point is [COURSE_BLUEPRINT.ipynb](/Users/oho/GitClone/CodexProjects/QuantumLearning/notebooks/COURSE_BLUEPRINT.ipynb).

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 older single-notebook sequence is still present as legacy reference material, but the canonical course path is now the full bundle architecture across all four technical bands.

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.

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/`.