[guluchen]

Issue: #181. Hub: #15. Base: main 6083e662. Do not merge before the PI says "merge".

Summary

New opt-in CC rule tokens in -cc-rules (all default off; with them off, every -v log on tier0+1 is byte-identical to main, both engines):

Token	What it does
sparse	Adds redundant parity rows R: the distinct sums r = h1 + h2 of two rows of the half's H with 0 < |r| <= max(|h1|, |h2|) (at most 4m, lightest first). Every element of ker H satisfies them. Used in the packing bound and the no-candidate dead end; the packing scan runs over H and R by weight class, lightest first.
sparsemrv	On halves where sparse added rows: fewest-candidate branching over the odd rows of H and R. Halves without added rows keep the lowest-index rule.
sparseov	Adds the same kind of pair sums of the half's stabilizer rows K to the GH-138 overlap rule, each with its own limit floor(|g|/2). Rows of H are not valid overlap rows (that is mutant 9).
xorunit	XOR unit propagation, to a fixpoint: an even row with one free qubit forbids it; an odd row with one free qubit is branched on first; an odd row with none is a dead end.

Rows are added only on TN_200_10_10, TN_250_10_15, TN_496_2_23to30 and the tier-0 codes LP_34_20_2, TN_36_8_3, TN_54_11_4, TN_72_14_4 (S0/rows_per_code.txt). On every other bundled code no pair sum qualifies, and the search runs the pre-GH-181 instantiation, so node counts are identical to main.

Candidate configuration: -cc-rules=excl,pack,orbf,parity,leaf,overlap,sparse,sparseov,sparsemrv.

Gate	Result
Tier 0	PASS. make test-cc PASS (server, 300 200 300). New Part X: 300 halves (263 with sparse rows, 71 with sparseov rows), 576 000 ladders, 0 bad. Mutants 19 / 20 / 21: 35 396 / 268 800, 36 281 / 307 200, 18 764 / 153 600 ladders wrong (all caught). make test-cc-flags 426 checks PASS. Identity with the tokens off: tier0+1 x 8 configurations (MaxSAT -no-card / -card-mto with and without -ub-pre; CC with and without -ub-search, -cc-stats, -cc-aut=off): 120/120 IDENTICAL. Answers: tier0-3 x 9 token variants, 207 runs, all correct. Independent GF(2) witness check: 119 ok, 0 bad.
Tier 1 / 2 / 3 / 4 (5-seed medians vs main CC)	0.908 / 0.791 / 0.998 / 0.081, max cell 1.000, no cell > 1.25. PASS.
Nodes	TN_200 0.118x, TN_250 0.052x (total, seed median). The reduction grows with w: TN_250 level 14, X half, 86.1M -> 3.40M (0.040x). Every other cell 1.000x.
Tier 5 (6 h)	TN_496_2_23to30 (open): lb 23 (main) -> lb 27 (candidate) in all three search orders (seed 0 and relabelled seeds 1, 2). Cross-check: REPRODUCED by an independent configuration (see 7a); no stem renamed. Main reaches lb 23 at 13 151 s; the candidate at 396 s (0.030x). Level 22: 26.5G -> 0.47G nodes (0.018x), 8 755 -> 248 s (0.028x). TN_496 is the only tier-5 code that gets rows.
xorunit	Reject. 5-11 % fewer nodes but 1.33-1.47x slower (TN_250, TN_200). On top of the candidate: 0.049x vs 0.050x nodes, 6.9 s vs 4.5 s. Kept as an opt-in token with tests, for the record.

Scientific semantics changed: no (opt-in pruning rules with written soundness proofs; the raised lower bound is reported as PLAUSIBLE and no stem is renamed). PI action required: yes (review; merge and adoption decisions; whether to rename TN_496 given the reproduced lb 27).

1. Soundness (full text: MODIFICATIONS.md, GH-181; code comments: src/cc/cc_half.h)

• Redundant rows. r = h1 + h2 gives r.v = 0 for every v in ker H. At a node S, any extension e in ker H has r.(e \ S) = r.S, so an odd r needs a qubit of e \ S.
  • So r stands in for a row of H in packing (disjoint candidate sets need distinct qubits, in any scan order), in the no-candidate dead end, and as a branching row (the branch over its free qubits contains one inside e; sibling exclusion keeps the first).
  • Rows of R are not used for syndrome-freeness, the parity rule, the leaf lookup or overlap.
  • Each row is recomputed from its two parents before use.
• sparseov. g = g1 + g2 for stabilizer rows has H g = 0 and G g = 0 (checked like K's rows). So e + g is in F, and the [Mac agent] CC engine: stabilizer-overlap pruning (Lee 2026) with forbidden-qubit propagation #138 argument holds with limit floor(|g|/2).
• xorunit. Take a row u with exactly one free qubit q, and any e in ker H that contains S and avoids the forbidden set.
  • u even: u.(e \ S) = 0 and (e \ S) & u is contained in {q}, so q is not in e.
  • u odd: q is in e.
  • The forbids keep every such e, so they chain with excl, orbf and overlap.

2. Implementation

All in src/cc/cc_half.{h,cc} unless noted.

• pair_sums: counts row overlaps first (no allocation per pair), then takes the symmetric difference for qualifying pairs only.
• R lives at word-aligned unified indices (64*mw onward), so its syndrome bits never touch nodd_ or the scans of H.
• Weight-class bitsets set the packing scan order.
• xorunit keeps per-row free counts (updated on every change of the forbidden set) and bitsets of rows with one free qubit and with none.
• The node functions are templates <bool E>. E = false is the old code path, used whenever a half has no added row, no added stabilizer row and no xorunit.
• cc_driver.cc: the tokens, -v lines, and a c cc-stats: ... gh181 spack sprune snocand ovtightx xuforbid xuforced xudead line, printed only with the tokens.
• distqldpc.cc: help text; -cc-mutant now accepts 19-21. Numbers 15-18 are left to [Mac agent] CC engine: fractional-charge / edge-cover node lower bounds #157 / [Mac agent] CC engine: orbit-compatible even-weight overlap tie-break #162.

3. Tier 0

• make test-cc (S0/test_cc_default.txt): CC_ENGINE_TESTS PASS. Part A: 115 200 ladders, 0 bad. Part B: 4 000 driver runs, 0 bad, including the new token configurations. All existing mutants are caught.
• New Part X:
  • Random halves: planted shifts, all-odd columns, and a TN-like third with heavily overlapping rows; K of three kinds.
  • 128 base rule subsets x 15 non-empty subsets of {sparse, sparseov, xorunit, sparsemrv}, seed (subset + combo) mod 3.
  • Every ladder is compared with enumeration, and every witness is checked in GF(2).
• New mutants, all caught:
  • 19: every redundant row has one qubit removed, so it is not in the row space of H;
  • 20: xorunit branches on an even unit row instead of forbidding its qubit;
  • 21: sparseov pair sums are taken from H instead of K, without the check.
• make test-cc-flags: 426 checks PASS (values, rejects, -v lines, mutants 19-21 named, no [Mac agent] CC engine: redundant sparse checks and XOR unit propagation #181 line without the tokens).
• Records: S0/identity_tier01.txt, S0/answers_results.jsonl, S0/witness_check.txt.

4. Tiers 1-4 (5-seed medians; main 6083e66 vs candidate; concurrent on pinned cores 6-19)

Tier	Code	main wall median (range)	sp wall median (range)	ratio	nodes sp/main (median over seeds)	search ns/node main -> sp	answers
1	LP_340_56_8	0.026 (0.025-0.027)	0.023 (0.023-0.024)	0.885	1.000	(process floor)	[8]
1	LP_442_68_10	0.029 (0.028-0.037)	0.027 (0.027-0.036)	0.931	1.000	(process floor)	[10]
2	BB_144_14_14	1.134 (1.101-1.227)	1.132 (1.106-1.224)	0.998	1.000	239 -> 240	[14]
2	BB_288_12_18	0.299 (0.288-0.308)	0.289 (0.285-0.306)	0.967	1.000	224 -> 223	[18]
2	GB_144_12_12	0.088 (0.077-0.096)	0.085 (0.074-0.094)	0.966	1.000	220 -> 220	[12]
2	LP_544_80_12	0.046 (0.039-0.050)	0.046 (0.038-0.048)	1.000	1.000	(process floor)	[12]
2	TN_108_2_12	2.124 (0.892-2.895)	2.090 (0.904-2.908)	0.984	1.000	255 -> 255	[12]
2	TN_200_10_10	0.168 (0.117-0.187)	0.045 (0.044-0.046)	0.268	0.118	(process floor)	[10]
3	LP_714_100_16	0.403 (0.292-0.447)	0.402 (0.286-0.445)	0.998	1.000	235 -> 233	[16]
3	TN_144_2_13	5.873 (2.065-7.149)	5.861 (2.072-7.125)	0.998	1.000	272 -> 270	[13]
4	TN_250_10_15	58.376 (33.389-60.345)	4.709 (3.495-5.018)	0.081	0.052	273 -> 434	[15]

Tier	cells	geomean	max cell	cells > 1.25
1	2	0.908	0.931	0
2	6	0.791	1.000	0
3	2	0.998	0.998	0
4	1	0.081	0.081	0

110 runs, science problems: []

Per-level nodes for TN_200 and TN_250: S1/panel_levels.md.

History (for transparency). Two earlier panels (S1/history/) failed Tier 1 on LP_442, with a ratio of 1.15-1.36:

• First binary: a 5 % per-node cost on cells without rows. Fixed by the <bool E> templates.
• Second binary: a pure process-floor effect.
  • User time was equal in both arms. Wall times are quantised by the parent's 10 ms waitpid poll (usleep(10000) in src/core/distqldpc.cc).
  • The first pair_sums allocated once per candidate pair, and that start-up cost pushed some 23 ms runs into the 33 ms slot.
  • Counting overlaps first removed it: in 15 + 15 repeats on LP_442, every run took 20-23 ms in both arms.

The panel above is the third run.

5. Ablation (TN_200, TN_250; 5 seeds; S1/ablation_table.md, S1/ablation_levels.md)

Code	arm	wall median (range) s	wall / main	total nodes median	nodes / main	answers
TN_200_10_10	main CC	0.156 (0.117-0.170)	1.000	559,890	1.000	[10]
TN_200_10_10	main + mrv	0.084 (0.076-0.092)	0.538	245,443	0.438	[10]
TN_200_10_10	+sparseov	0.157 (0.124-0.165)	1.006	522,066	0.932	[10]
TN_200_10_10	+xorunit	0.229 (0.174-0.235)	1.468	515,504	0.921	[10]
TN_200_10_10	+sparse	0.084 (0.076-0.094)	0.538	208,958	0.373	[10]
TN_200_10_10	+sparse,sparseov	0.086 (0.076-0.091)	0.551	191,509	0.342	[10]
TN_200_10_10	+sparse,sparsemrv	0.051 (0.044-0.053)	0.327	72,498	0.129	[10]
TN_200_10_10	+sparse,sparseov,sparsemrv (candidate)	0.045 (0.042-0.056)	0.288	65,003	0.116	[10]
TN_200_10_10	+sparse,sparseov,sparsemrv,xorunit	0.067 (0.064-0.072)	0.429	63,467	0.113	[10]
TN_250_10_15	main CC	59.948 (32.045-62.737)	1.000	212,861,906	1.000	[15]
TN_250_10_15	main + mrv	28.140 (18.162-29.412)	0.469	101,140,763	0.475	[15]
TN_250_10_15	+sparseov	54.517 (29.088-57.207)	0.909	179,150,889	0.842	[15]
TN_250_10_15	+xorunit	79.670 (47.203-81.882)	1.329	190,433,202	0.895	[15]
TN_250_10_15	+sparse	15.364 (8.335-17.099)	0.256	45,819,554	0.215	[15]
TN_250_10_15	+sparse,sparseov	13.509 (7.259-14.951)	0.225	37,595,294	0.177	[15]
TN_250_10_15	+sparse,sparsemrv	5.116 (3.661-5.341)	0.085	12,762,366	0.060	[15]
TN_250_10_15	+sparse,sparseov,sparsemrv (candidate)	4.529 (3.208-4.701)	0.076	10,640,558	0.050	[15]
TN_250_10_15	+sparse,sparseov,sparsemrv,xorunit	6.931 (4.984-7.391)	0.116	10,416,790	0.049	[15]

Exploration that chose the design (pre/, exploration binaries from pre/exploration_knobs.diff):

• Packing order on TN_250:
  • H rows first, then R: 0.42x;
  • R first, max with H first: 0.36x;
  • weight classes, lightest first: 0.30x, chosen (0.26x with sparseov).
• A lighter xorunit variant (no counters; only the even rows of the last added qubit) was slower than the full one, at equal nodes.
• Forced-unit branching alone was 1.23x slower.

6. Optional: combined with GH-162 tiebreak (PR #180)

Built from a scratch merge of the GH-162 code commit 97c86299, not pushed. xorunit and tiebreak cannot be combined there: the tiebreak routines bypass the xorunit counters.

Panel main vs sparse,sparseov,sparsemrv,tiebreak (TB/panel_table.md): Tier 1 / 2 / 3 / 4 = 1.113 / 0.753 / 0.996 / 0.067.

• TN_250: 0.067x time, 0.040x nodes.
• BB_288: 0.761x, from tiebreak.
• LP_442 (Tier 1, 1.35): the same 10 ms poll artifact. The scratch merge predates the pair_sums fix, and its nodes are identical to main.

Combined Part X with tiebreak (TB/test_combo_partX.txt): 300 halves, 576 000 ladders, 0 bad, and mutants 19-21 still caught. The FAIL(2) in that file is only the existing Part A/B mutant expectations, which a reduced 10 5 run cannot meet.

7. Tier 5 (6 h, default seed; main CC alongside in the same session, cores 20-23)

Code	main	sp	time to the main arm final value: main -> sp s (ratio)	largest level done by both: nodes main -> sp (ratio), s main -> sp (ratio)
TN_496_2_23to30	TIMEOUT lb 23	TIMEOUT lb 27	13151 -> 396 (0.030)	22 (X -> X): 26543.9M -> 465.1M (0.018), 8755 -> 248 (0.028)

geomean over codes of the largest level done by both (levels > 1 s): nodes 0.018, time 0.028 (1 codes)

Bound events (lb value@seconds, from 18) where the final value changed:

Code	old	new
TN_496_2_23to30	18@55 19@162 20@500 21@1473 22@4395 23@13151 23@21600	18@4 19@9 20@23 21@58 22@147 23@396 24@1094 25@2889 26@7722 27@20690 27@21600

2 runs, science problems: []

Cross-checks (relabelled seeds, new arm):

run	result	lb events
x5.TN_496_2_23to30.sp.s1	TIMEOUT lb 27	18@3 19@9 20@22 21@54 22@137 23@365 24@1012 25@2652 26@7167 27@18709 27@21600
x5.TN_496_2_23to30.sp.s2	TIMEOUT lb 27	18@3 19@8 20@21 21@52 22@135 23@379 24@1011 25@2680 26@7151 27@19045 27@21600

Status of the TN_496 bound: PLAUSIBLE.

• All four runs used the 21 600 s limit.
• Every candidate run proved levels 23-26 EMPTY on the X half; the verified dual map mirrors the Z half. The ladder is contiguous from 1.
• The three agreeing runs are three search orders of the same implementation. An independent cross-check (another implementation, or main CC with a much longer budget) is still needed before any rename.
• The stem stays TN_496_2_23to30; the upper bound 30 is unchanged.
• The seed-2 job line carries -seed=1 -seed=2. The last -seed wins (checked: -v prints cc-seed 2). See T5/NOTE.txt.

7a. Cross-check of TN_496 lb 27 (8 h each, cores 4-9; XC27/NOTE.md)

The configurations deliberately differ from the run that found lb 27 (sparse,sparseov,sparsemrv, seeds 0/1/2):

Run	Rules (on top of the defaults)	Seed	Final lb	Levels proved
(a)	sparse only	3 / 4	25 / 25	1-24 EMPTY
(b)	sparse,sparseov,sparsemrv,tiebreak (scratch merge with GH-162 97c86299, different binary)	0 / 3	27 / 27 (at 11 864 / 10 739 s)	1-26 EMPTY
extra	sparse,sparsemrv (no sparseov)	3 / 4	26 / 26	1-25 EMPTY

• All levels are on the X half (verified dual map), contiguous from 1. There is no FOUND, INCONSISTENT, TRAP or error line, and the upper bound stays 30.
• (c), the MaxSAT path started at level 23, is skipped: no such entry point exists. There is no lower-bound or start-cap flag, and the dumps only give the full optimisation instance.

Verdict: REPRODUCED. (b) reaches lb 27 with every level EMPTY, in two seeds. (a) and the extra arm stop earlier within 8 h but agree: every level they completed is EMPTY.

Caveat: every run uses DistQLDPC's CC engine, i.e. the same level framework and driver. (b) differs in binary, overlap rule and search order.

The stem is not renamed; the PI decides.

8. Recommendation

• Recommend sparse,sparseov,sparsemrv as an adoption candidate (PI decision).
  • It passes Tiers 0-5: Tier 1-4 geomeans 0.908 / 0.791 / 0.998 / 0.081, max cell 1.000.
  • TN_250 runs 12x faster, TN_200 3.7x.
  • TN_496's 6 h lower bound rises from 23 to 27 (reproduced by an independent configuration, 7a).
  • Everywhere else it is idle with identical nodes.
• Before any default change:
  • a PI decision on the token set (all three, or sparse alone: 0.26x on TN_250);
  • a PI decision on the TN_496 rename (lb 27 reproduced, 7a);
  • re-recorded baselines.
• xorunit: reject (at most 11 % fewer nodes, 1.3-1.5x slower).
• Combining with [Mac agent] CC engine: orbit-compatible even-weight overlap tie-break #162 tiebreak works (TN_250 0.067x, BB_288 0.76x). A real merge needs the tiebreak routines to use blk_up/blk_down if xorunit is kept.

Credit

• Redundant pair-XOR checks: Qubitserf (github.com/Quantinuum/Qubitserf, commit 04b9349, augment_sparse_checks, S. Cercelescu, MIT). Idea only; no code was copied.
• Puchert and Tillmann, arXiv:2004.03387 (redundant parity-check cuts).
• Okada and Kasai, cpm-ldpc-distance (forced unit).

Credited in NOTICE, MODIFICATIONS.md and code comments.

Files

optimization/experiments/GH-181/: runner/, S0/, S1/, TB/, T5/, pre/.

Frozen server binaries in /home/yfc/mac-agent-20261009/frozen/:

• server-main-6083e66;
• server-gh181-9b237b0: tree of 9930c679, used for Tiers 0-4;
• server-gh181-07b5e3d: tree of 091c1056, used for Tier 5. Its per-level node lines are identical to 9b237b0 on all 110 panel runs.

The commits were rebased only to add trailers; the trees are unchanged.

🤖 Generated with Claude Code