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/
├── assets/figures/
├── configs/
├── notebooks/
├── src/
├── tests/
├── .venv/
├── pyproject.toml
└── README.md
```

## Quick Start

Use the repo-local Python 3.12 environment.

```bash
cd /Users/oho/GitClone/CodexProjects/QuantumLearning
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
```

Launch Jupyter from the project root with the repo-local wrapper so the notebooks, kernel, and local config stay aligned.

```bash
./scripts/start_jupyter.sh
```

The launcher writes only inside the project directory, opens the repo-local `QuantumLearning (.venv)` kernel, and defaults to the onboarding notebook.

If you want a different local port:

```bash
./scripts/start_jupyter.sh 8890
```

Run the tests:

```bash
source .venv/bin/activate
pytest
```

Run the measured local coverage report:

```bash
source .venv/bin/activate
pytest --cov=quantum_learning --cov-report=term-missing
```

Install the project-local browser runtime used by the real JupyterLab UX tests:

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

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