skills · diff
git:20260525.485b99d to git:20260526.6d8ac92
83 added, 35 removed. Audit C to C.
- # skills/
+ # LightStim — Skills Entry Point
- Self-contained executable examples for using the LightStim API.
- Each script can be run from the repo root with `python skills/<script>.py`.
- Each demonstrates one complete workflow and serves as a reference for LLM-assisted development.
+ Read this first. It orients you to the project and routes you to the right skill.
- | Script | What it demonstrates |
- |--------|----------------------|
- | `01_memory_surface_code.py` | Build a rotated surface code Z-memory circuit end-to-end |
- | `02_simulate_and_decode.py` | Run SimulationPipeline + PyMatching, read logical error rate |
- | `03_transversal_cnot.py` | Two-patch transversal CNOT between unrotated surface codes |
- | `04_lattice_surgery_cnot.py` | 3-patch lattice surgery CNOT (control + target + ancilla) |
- | `05_state_injection.py` | Inject Z/X/Y logical states with post-selection |
- | `06_custom_noise_model.py` | Compare circuit_level / phenomenological / code_capacity noise models |
- | `07_extend_new_qec_code.py` | Template for adding a new QEC code (QECPatch + SE_block) |
+ ---
- See also `skills/gotchas/SKILL.md` — a catalogue of known pitfalls and debugging patterns.
+ ## What is LightStim?
- ## Usage
+ LightStim is a modular QEC framework built on [Stim](https://github.com/quantumlib/Stim).
+ Its core value is **automatic detector generation**: you define the QEC code and the
+ syndrome extraction schedule; LightStim computes `DETECTOR` and `OBSERVABLE_INCLUDE`
+ instructions automatically via symplectic tableau tracking.
- ```bash
- # From repo root (venv activated)
- python skills/01_memory_surface_code.py
- python skills/07_extend_new_qec_code.py
+ Key data flow:
```
+ QECPatch → QECSystem → CircuitBuilder + SyndromeTracker → stim.Circuit
+ ↓
+ NoiseInjector → SimulationPipeline → LER
+ ```
- ## Key API entry points
+ ---
+ ## Which skill do you need?
+
+ | I want to… | Read this skill |
+ |---|---|
+ | Build a circuit for a new protocol from scratch | [`builder-tracker-api/`](builder-tracker-api/SKILL.md) |
+ | Design a new lattice surgery coupler (multi-patch) | [`logical-coupler-design/`](logical-coupler-design/SKILL.md) |
+ | Run a simulation and get logical error rate | [`simulate-decode/`](simulate-decode/SKILL.md) |
+ | Configure noise models (circuit-level, phenomenological…) | [`custom-noise/`](custom-noise/SKILL.md) |
+ | Add a new QEC code (new stabilizer geometry) | [`extend-new-code/`](extend-new-code/SKILL.md) |
+ | Write or update a protocol notebook | [`notebook-workflow/`](notebook-workflow/SKILL.md) |
+ | Debug unexpected detector counts, LER≈50%, or tracker errors | [`gotchas/`](gotchas/SKILL.md) |
+
+ When in doubt, start with **`builder-tracker-api/`** — it covers the core API that every
+ other skill builds on.
+
+ ---
+
+ ## Key conventions (apply everywhere)
+
+ **Imports** — always use `lightstim.*`, never `src.*`:
```python
- # Build any QEC code
- from lightstim.qec_code.surface_code.rotated import RotatedSurfaceCode, RotatedSurfaceCodeExtractionBlock
+ from lightstim.qec_code.surface_code.rotated import RotatedSurfaceCode
from lightstim.ir.qec_system import QECSystem
+ from lightstim.ir.builder import CircuitBuilder
+ from lightstim.ir.tracker import SyndromeTracker
+ from lightstim.noise.config import NoiseConfig
+ from lightstim.simulation.decoder_backend import SimulationPipeline, DecoderConfig
+ ```
- system = QECSystem()
- system.add_patch(RotatedSurfaceCode(distance=3), name='main')
+ **Python environment** — always use `venv/bin/python`, never system Python:
+ ```bash
+ PYTHONPATH=. venv/bin/python my_script.py
+ ```
+ Using the wrong Python causes `cudaq_qec` to not be found → LER ≈ 99%.
- # Run a memory experiment
- from lightstim.protocols.memory import MemoryExperiment
- from lightstim.noise.config import NoiseConfig
+ **Decoder choice** — depends on circuit type:
+ - Surface/toric/repetition → `pymatching` (fast, correct)
+ - Color code, BB codes, PQRM → `mwpf` or `bposd` (handles hyperedges)
+ - GPU → `nv-qldpc-decoder` with `num_workers=1`
+ - See `gotchas/SKILL.md` §7 for the full decision table
- exp = MemoryExperiment(system, RotatedSurfaceCodeExtractionBlock, rounds=3,
- noise_params=NoiseConfig(p_2q=1e-3, p_meas=1e-3))
- circuit = exp.build()
+ **Benchmark scripts** — must use per-task checkpointing (append one CSV row per task).
+ See `skills/README.md` → "Adding a new benchmark" for the full convention.
- # Decode + get LER
- from lightstim.simulation.decoder_backend import SimulationPipeline, DecoderConfig
+ ---
- stats = SimulationPipeline(decoder_config=DecoderConfig('pymatching'),
- max_errors=200, print_progress=False).run(circuit)
- print(stats.logical_error_rate)
+ ## Repository layout (quick reference)
+
```
+ lightstim/ Core library
+ qec_code/ QEC code definitions (QECPatch subclasses)
+ ir/ CircuitBuilder, SyndromeTracker, QECSystem
+ noise/ NoiseConfig, NoiseInjector, noise rules
+ simulation/ SimulationPipeline, decoder backends
+ protocols/ Packaged protocol implementations
+ plot/ Paper-style plot utilities
+
+ notebooks/ Demo notebooks (one per protocol)
+ benchmarks/ Large-scale sweep runners + plot scripts
+ paper_artifact/ Reproducible paper figures (precomputed data + plot scripts)
+ skills/ This directory — task-oriented LLM guidance
+ docs/api/ Formal API reference (class hierarchy)
+ ```
+
+ ---
+
+ ## API docs vs skills
+
+ | | `docs/api/` | `skills/` |
+ |---|---|---|
+ | Organized by | What exists (class hierarchy) | What you want to do |
+ | Coverage | Complete (every parameter) | Curated (task-relevant) |
+ | Stance | Neutral | Opinionated — tells you the right path |
+ | Failure modes | Not covered | Explicitly covered in gotchas |
+
+ Use `docs/api/` when you need a precise method signature.
+ Use a skill when you need to know *how* to accomplish a goal.