QEC Challenge

Live leaderboard: https://unitaryfoundation.github.io/qldpc-challenge/

A public, automatically verified leaderboard for quantum low-density parity-check (qLDPC) codes. Submit a code, the verifier checks it, and if it holds up it goes on the board.

The leaderboard site is generated into docs/ by site/build.py (run uv run python site/build.py); open docs/index.html to view it.

The badges above are rendered by shields.io from the published board data (the live stats.json), so they always reflect the current numbers. They read the deployed file directly rather than a committed image, so nothing has to be regenerated and re-committed to keep them in sync.

Unlike a single-number competition, a quantum code trades several quantities against each other (physical qubits n, logical qubits k, distance d, check weight, geometric locality). So the boards are a computed grid of locality class by check weight (membership derived from the parity checks and the layout, not self-declared), and within each cell the ranking is a Pareto frontier rather than one winner. Construction family is a separate filter tag. See TRACKS.md.

Start here

You want to...	Read
Submit a code you already have	CONTRIBUTING.md — one command: ./qldpc submit
Have an LLM find and submit a code	Contribute with an LLM (a ready-to-paste prompt) and research/AUTORESEARCH.md (the full research-loop manual)
Understand the boards and the targets to beat	TRACKS.md — especially the "Reference bars" section
Point a coding agent at this repo	AGENTS.md

Before starting a search, ./qldpc recent summarizes what landed lately (codes, research notes, fieldnotes), so you begin from the community's current frontier of knowledge rather than rediscovering it.

Installation

This repo uses uv to manage the Python environment. Install it from the uv docs; after that uv run sets up the environment on first use, so there is no separate install step here.

Verify a code locally:

uv run python verify/qldpc_verify.py codes/your-code.json

Build the leaderboard site:

uv run python site/build.py
# then open docs/index.html

Run research tools:

uv run python research/test_smoke.py   # the starter-kit loop, end to end

Submitting

You bring parity checks H_X and H_Z; one command turns them into a verified, PR-ready submission:

./qldpc submit mycode.npz --authors @yourhandle

It computes n and k, finds the distance witness for you, assembles the schema-valid JSON, runs the full verifier locally (the same gate CI runs), and writes codes/<n>-<k>-<d>.json. If verification fails, nothing is written and you see exactly which check failed. CONTRIBUTING.md has all the flags (layouts, provenance, --open-pr) and the full walkthrough.

A submission is one JSON file in codes/, one new code per PR. CI re-runs the verifier; a green check means the code's cheap, trustless properties are confirmed:

• n, k (recomputed exactly over GF(2)), CSS commutation, max check weight, and geometric locality against your stated layout, all machine-checked.
• The distance you claim must come with a witness: an explicit logical operator of that weight. The verifier confirms it is a genuine nontrivial logical, which certifies the distance as an upper bound with no trust required.

Claiming a distance is exact (not just an upper bound) additionally requires server certification, a separate and more expensive step.

Prefer to write the JSON yourself? Follow schema/code.schema.json (schema/SCHEMA.md documents each field — see the "By hand" section of CONTRIBUTING.md) and verify locally before opening a PR:

uv run python verify/qldpc_verify.py codes/your-code.json

Bring your LLM

If you have an LLM or coding agent, it can do the whole loop — pick a target from the reference bars, search a construction family, verify locally, and open the PR from your account. This is the lowest-effort way to participate: paste the ready-made prompt from Contribute with an LLM into your agent. The tool-agnostic operating manual for the research loop (constructors, the distance surrogate, packaging, and the validation gate) is research/AUTORESEARCH.md.