[guluchen]

Implements the PI-approved benchmark tier layout and renames (decisions of 2026-10-11, spec BENCHMARK_TIERS_SPEC.md). Base: main 7eadd54.

Move / rename table

All 200 matrix files (50 codes x Hx/Hz/Gx/Gz) moved with git mv from data/matrices/ into data/matrices/tier0 … tier5. 190 are byte-identical renames. The other 10 are the Gx/Gz files of the 5 renamed codes: only their # header comment changed, to name the new stem (parity <new>_Hx.txt). No matrix rows changed. data/matrices/ itself now holds only README.md.

Tier	#	Codes
tier0 (correctness/smoke)	10	BB_72_12_6, LP_34_20_2, LP_136_32_4, TN_36_8_3, TN_36_8_4, TN_54_11_4, TN_72_14_4, TN_72_8_8, TN_108_2_12, TN_200_10_10
tier1	4	BB_90_8_10, GB_144_12_8, BB_108_8_10, LP_238_44_6
tier2	1	LP_340_56_8
tier3	6	BB_144_12_12, GB_144_12_12, BB_144_14_14, LP_442_68_10, LP_544_80_12, TN_144_2_13
tier4 (2000 s)	3	TN_250_10_15, BB_288_12_unknown, LP_714_100_unknown
tier5 (21600 s)	26	BB_360_12_unknown, LP_1768_224_unknown, LP_1054_140_unknown, LP_1020_136_unknown, LP_1428_184_unknown, TN_648_10_unknown, BB_756_16_34, BB_864_4_40, BB_1080_4_54, TN_180_2_17, TN_216_4_18, TN_252_2_21, TN_288_2_24, TN_324_4_25, TN_360_4_unknown, TN_396_4_26, TN_432_8_33, TN_468_4_31, TN_496_2_32, TN_504_2_45, TN_540_4_40, TN_576_2_57, TN_576_2_59, TN_612_2_52, TN_648_14_50, TN_684_2_29

Old	New	Check
PK_31	tier5/LP_1054_140_unknown	n = 1054 (Hx columns), k = 140 (Gx rows)
xu_30	tier5/LP_1020_136_unknown	n = 1020, k = 136
xu_42	tier5/LP_1428_184_unknown	n = 1428, k = 184
TN_648_10_71	tier5/TN_648_10_unknown	bundled logicals have weight 52, so d <= 52
TN_360_4_24	tier5/TN_360_4_unknown	spec update (PI, 2026-10-11): matrices identical to QDistSAT's data/tier5/TN_360_4_unknown_*. After the Gx/Gz header fix, cmp shows all four files byte-identical to QDistSAT's

BB_288_12_unknown and LP_714_100_unknown keep their names. The coordinator will rename them after cross-checks. I checked every stem's n and k against its matrices: all 50 match.

Resolver change (src/core/distqldpc.cc, the only source change)

resolve_prefix: a bare code name (no /) resolves to data/matrices/<code> if <code>_Hx.txt exists there. Otherwise it resolves to the first of data/matrices/tier0 … tier5 (in that order) that contains <code>_Hx.txt. If none does, it falls back to the old data/matrices/<code>, so the error messages are unchanged (error: cannot open data/matrices/NOPE_1_Hx.txt). Paths containing / are used unchanged. The header comment and usage line are updated. Solver behaviour is unchanged; only the -v c Hx/Hz/Gx/Gz: lines now show the tier path.

Scripts and docs

• scripts/smoke_test.sh now expects c Hx: data/matrices/tier0/LP_34_20_2_Hx.txt.
• scripts/benchmark_matrices.py:
  • Looks codes up in --matrices-dir, then in its tier*/ subdirectories (recursive, natural order, first complete match; same order as the binary). It passes the resolved tier path to the solver.
  • --all finds all 50 codes. The CLI is unchanged, and a single tier dir (--matrices-dir data/matrices/tier1) also works.
  • The DEFAULT/ADVANCED lists and ADVANCED_REFERENCE_SEC contain no renamed stems, so they are unchanged.
• scripts/compute_logicals.py, scripts/preprocess_matrices.py:
  • Help text and docstrings now say the bundled codes live in data/matrices/tierN. Both take one flat dir via --dir / --src.
  • preprocess_matrices.py now exits with an error when its source dir has no codes. Before, the default --src data/matrices would have wiped data/s1 and data/s2 and written nothing.
• README.md, MODIFICATIONS.md (resolver row) and NOTICE section 5 now cover the tier layout. NOTICE records the new names with "was PK_31 / xu_30 / xu_42 / TN_648_10_71 / TN_360_4_24", and all attribution is kept.
• New data/matrices/README.md: tier table with n/k/d, per-tier timeouts, naming rule, rename history and the open items below.
• I did not touch optimization/experiments/** or .github/workflows/*. AGENTS.md, docs/*.md and tests/* contain no references to the old stems or to data/matrices/<stem>, so they are unchanged.

Test evidence (macOS arm64, Apple clang)

• make clean; make CXX="c++ -Wno-reserved-user-defined-literal": OK.
• bash scripts/smoke_test.sh: passed.
• python3 -B scripts/test_partition_soft_literals.py: 11 inputs x 1024 assignments, passed. tests/test_partition_soft_literals.cc (GH58 oracle; uses no data paths) built against build/*.o: GH58_PARTITION_ORACLE_PASS cases=80.
• All 50 codes, ./bin/distqldpc -v -cpu-lim=2 -no-card <stem> (4 in parallel): 50/50 print c Hx: data/matrices/<tierN>/<stem>_Hx.txt matching the spec's tier, with 0 cannot open errors. 12 finish within 2 s with the expected d; the rest hit the 2 s limit (s UNKNOWN, as expected).
• Explicit paths still work: data/matrices/tier0/TN_36_8_3 gives o 3, and an absolute path to tier3/BB_144_12_12 resolves as given. A flat data/matrices/<code> takes precedence (checked in a scratch flat copy).
• Frozen main binary (7eadd54) on a scratch flat copy vs this branch, -v, for 5 codes (BB_72_12_6, LP_34_20_2, LP_136_32_4, TN_36_8_3, TN_72_8_8): outputs identical apart from the 8 c Hx/Hz/Gx/Gz: path lines (0 other differing lines). Results: d = 6, 2, 4, 3, 8.
• Renamed codes: -symbreak-report output is identical between the frozen main on the old flat names and this branch on the new names, once the stem and the detect_cpu timing are masked. Matrix dimensions are identical too.
• scripts/benchmark_matrices.py --all --timeout 1 -j 4: 50 codes, error = 0. --codes LP_1054_140_unknown TN_648_10_unknown runs on the tier5 paths.
• Cross-repo check: the workflow uses QDistSAT's own data, so this PR does not affect it. It was still dispatched on the one-commit branch ci/xrepo-data-tiers (commit 3073c7b, tree = this branch's head 53adf13, parent 7eadd54): run 38109630364 success. LP_136_32_4 gave d=4 and BB_108_8_10 gave d=10 in both no-card and card-mto, semantic match YES 4/4. The push-triggered CI (smoke) on that branch, run 38109630538, also passed. An earlier dispatch on the pre-TN_360 tree (9d24e87, run 38109423548) also passed 4/4.
• TN_360_4_unknown: -symbreak-report output is identical to the frozen main on the old TN_360_4_24 (stem and timing masked). The bare name resolves to tier5, and the old name now gives cannot open data/matrices/TN_360_4_24_Hx.txt. The 50-code check was re-run after this rename: 50/50 OK.

Open items

• TN_648_10_unknown: d <= 52; the exact distance is unknown.
• BB_288_12_unknown / LP_714_100_unknown: main reports d = 18 and d = 16. These are pending results awaiting internal cross-checks before the rename to BB_288_12_18 / LP_714_100_16.
• docs/OPTIMIZATION_LOOP_POLICY.md fixes no numeric timeouts for Tiers 1–3, so data/matrices/README.md does not invent any; limits are pre-registered per experiment.
• The policy's Tier 3 seven-case set includes TN_250_10_15, but the spec puts that code in tier4/. I did not edit the policy; the PI may want to reconcile the two.

🤖 Generated with Claude Code

[guluchen]

Coordinator note: the policy side (Tier 3 = six cases without TN_250_10_15, Tier 4 with a 2000 s limit, Tier 5 with a 6 h limit, tier directories) is in PR #110; #110 and #111 (plus guluchen/QDistSAT#5) are meant to be merged together.