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

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

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