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

QuantumLearning/
├── assets/figures/
├── configs/
├── notebooks/
├── src/
├── tests/
├── .venv/
├── pyproject.toml
└── README.md

Quick Start

Use the repo-local Python 3.12 environment.

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.

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

./scripts/start_jupyter.sh 8890

Run the tests:

source .venv/bin/activate
pytest

Run the measured local coverage report:

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:

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. The assessment and competence model is documented in 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.

The full Foundations band is now rebuilt as module bundles:

• Module 1: Principles and Circuit Literacy
• Module 2: Qubit and Statevector Intuition
• Module 3: Gates and Measurement

The Qiskit Engineering band is also rebuilt:

• Module 4: Circuit Construction and Analysis
• Module 5: Transpilation and Visualization
• Module 6: Simulation and Noise Models

The Algorithmic Design band is now rebuilt too:

• Module 7: Deutsch Family and Oracle Thinking
• Module 8: Bernstein-Vazirani and Structured Oracles
• Module 9: QFT and Periodic Structure
• Module 10: Grover and Amplitude Amplification

The Professional Design band is now rebuilt as well:

• Module 11: Qiskit Patterns and Workflow Design
• Module 12: Hardware-Aware Redesign Studio
• Module 13: Noise-Aware Verification and Mitigation
• Module 14: Capstone Circuit 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 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.