studying-qldpc-codes-with-qldpc

name	studying-qldpc-codes-with-qldpc
description	Guides construction, inspection, and experiment planning for quantum LDPC codes using the qLDPC package, while keeping a clear boundary between code-design analysis and later executable circuit or decoder workflows.
version	0.1.0
author	QEC Research Skills
license	MIT
tags	["QEC","QLDPC","qLDPC","Codes","Analysis"]
dependencies	["qec-research"]

Studying QLDPC Codes With qLDPC

What This Skill Is For

Use this skill when the main task is code construction or inspection around quantum LDPC families:

• build or inspect candidate QLDPC constructions,
• reason about parity-check structure, logical operators, or distance estimates,
• plan downstream memory or threshold experiments from a code-design starting point,
• decide whether qLDPC is the right package or whether another toolkit fits better.

When To Use It Versus Alternatives

Use this skill when the work starts from a code family or parity-check description.

Use building-stim-circuits when the task is already about executable stabilizer circuits and detector-model artifacts.

Use decoding-with-ldpc when registered detector-model or trajectory artifacts already exist and the task is decoder execution rather than code construction.

Do not present this skill as proof that the repo already ships a qLDPC adapter. The current lane is documentation-first.

Required Artifacts And Assumptions

Expected inputs:

• a code family or construction idea,
• target parameters such as block length, rate, distance regime, or field size,
• the intended downstream question such as structural analysis, decoder benchmarking, or manuscript support.

Expected outputs:

• a code-construction brief,
• a list of package-relevant capabilities and caveats,
• explicit next artifacts needed before any executable benchmarking claim.

Assumptions to make explicit:

• whether the task is binary CSS, non-binary, subsystem, or more general stabilizer work,
• whether the output needs parity-check matrices, logical operators, distance estimates, or circuit hooks,
• whether the environment can support qLDPC and its optional dependencies,
• whether the request is really better served by PyMatching, PanQEC, qecsim, tesseract-decoder, or another toolkit.

Standard Workflow Checklist

1. Read research-state.yaml to confirm the current repo phase and toolkit assumptions.
2. Read references/qldpc-package-fit.md before choosing qLDPC.
3. State the target code family, parameter regime, and downstream research question.
4. Separate code-design outputs from later execution outputs so the plan does not blur construction with benchmarking.
5. Record any environment caveat, especially Python-version or optional-tooling requirements, before recommending implementation work.
6. If the request actually centers on graphlike detector-model decoding, route to a decoder-oriented package instead of forcing qLDPC.

Validation Loop

Before closing work:

1. confirm the code family and parameter regime are explicit,
2. confirm qLDPC is being used for a construction or analysis task it actually fits,
3. confirm any downstream circuit or decoder step is labeled as planned rather than already integrated,
4. confirm environment caveats are visible if they affect installability or reproducibility.

Common Issues And Fixes

Construction-execution blur

Problem: a plan jumps from parity checks to executable benchmark claims without defining the intermediate artifacts.

Fix: add the missing artifact handoff explicitly, such as code summary, circuit synthesis plan, or decoder task specification.

Package mismatch

Problem: qLDPC gets chosen for a task that is really graph matching, threshold sweeping, or topological-code simulation.

Fix: reroute using the package-selection notes in references/qldpc-package-fit.md.

Hidden environment constraints

Problem: the repo starts to imply qLDPC is available in the current baseline even when the environment does not satisfy its packaging requirements.

Fix: keep the lane documentation-first until an adapter and health-check story exist.

References

• references/api.md
• references/examples.md
• references/qldpc-package-fit.md
• ../../docs/TOOLKIT_REGISTRY.md
• ../../01-circuits/building-stim-circuits/SKILL.md
• ../../02-decoders/decoding-with-ldpc/SKILL.md