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

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:

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 ./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. 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 ./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 ./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 ./scripts/app.sh start --port 8890

If you want to restart the whole Jupyter layer cleanly:

bash ./scripts/app.sh restart

If you want to inspect the live log:

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 ./scripts/app.sh reset-state

Run the tests:

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

Run the measured local coverage report:

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:

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

The consumer entry point is START_HERE.ipynb. The first serious orientation notebook after that is 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
• 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 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 for the short startup checklist. See OPERATIONS.md for setup on another Mac, monitoring, validation, and recovery. See AGENT_CONTEXT.md and 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/.