Skip to content

rational: X-a3, the 4th-band stage admitted (decision 6 reopened) - #110

Merged
tap merged 3 commits into
mainfrom
claude/sample-rate-solutions-comparison-mqc190
Nov 21, 2026
Merged

tap merged 3 commits into
mainfrom
claude/sample-rate-solutions-comparison-mqc190

Conversation

@tap

@tap tap commented Nov 21, 2026

Copy link
Copy Markdown
Owner

What this changes

X-a3 of docs/X4_X8_PLAN.md. Decision 6 is amended and X3 lands: up4 / down4 become single 4th-band stages, and the coverage matrix may now choose them. The selection frozen in X-a2 (FROZEN_SELECTION) is removed, so the matrix chooses each row's chain freely again.

Matrix

  • 46 rows change chain at economy: 30 within a family and 16 across families. This is exactly what X-a2 measured.
  • The mean economy cost over the 182 rows falls from 87.76 to 84.59 MAC/out (−3.6 %).
  • ×4 stays two half-band stages (R3), which costs fewer MACs.

Chains

  • 12 named chains are added:
    • up: up2_up4, up3_up4, up2_up4_up2, up2_up3_up4, up2_up4_up4, up3_up4_up4
    • down: down4_down2, down4_down3, down2_down4_down2, down4_down3_down2, down4_down4_down2, down4_down4_down3
  • 10 chains that no row runs any more are retired.
  • Four chains stay for the per-tier matrix (X-a4): up2_up6, up2_up8, down6_down2 and down8_down2. No row runs them at economy; X-a4 selects them at transparent.

C ABI (X7)

  • The new chains take the new values 28–39.
  • The retired values (10, 11, 14–16, 21, 22, 25–27) are never reused. create_format rejects them through a table.
  • TAP_SR_RATIONAL_CHAIN_COUNT is retired. Its replacement is TAP_SR_RATIONAL_CHAIN_END = 40, one past the largest value ever assigned.
  • create_stage accepts 4/1 and 1/4. The binding maps chain names to values through a table.
  • The set of exported symbols is unchanged.

Vocabulary gate

  • retired_words.txt adds the ten retired C++ chain names, their C constants and TAP_SR_RATIONAL_CHAIN_COUNT.

Design tables

  • The relaxation tables drop the design divisors 9 and 16, because no stage in the new selection uses them. The tables go from 10 rows to 8; every remaining pin is unchanged.

Ratchet and ceilings

  • New icount workload: down4_down2_q15_eco.
  • New worst-call scenarios: callmax_down4_float and callmax_down4_q15.
  • New host workloads: down4_float_2ch and down4_float_12ch.
  • A second probe set for the ↑4 / ↓4 stages, keys f32_by4 / q15_by4 / q31_by4, with README rows.
  • No existing baseline was changed.

Record
Decision 6's amendment is recorded in:

  • rational/PLAN.md: section 1, R3, R16, 2.1, 3.1–3.6, sections 5 and 6 with an X-a3 record, decision 6, and version row v0.18
  • rational/CLAUDE.md and rational/README.md
  • the book: part 7's charter.md, chain.md and proof.md
  • docs/ROADMAP.md

docs/X4_X8_PLAN.md marks X-a2 done (#109) and records X-a3's actual counts.

Why

Since X-a2 (#109), the designer β follows the rule A+4, and the spike measurements say a 4th-band stage is cheaper inside the chains by 8 and above (X-0, X3, X17). X-a2 froze each row's chain so that the β change and the change of chain set would land in separate PRs. This PR makes the chain-set change.

Verification

  • GCC 13 Release, with -Werror on all three engines and the C ABI: ctest 351/351 (rational 142).
  • Clang 18 -Werror, with the C ABI and the icount bench: 351/351.
  • clang-tidy 18: clean on all 16 rational translation units.
  • clang-format 18.1.3: clean.
  • Vocabulary gate: clean. README freshness checks: clean. matrix.py diff: 0 rows.
  • Fixed point: every Q15 stage, ↑4 and ↓4 included, reaches the 70 dB tier.
    • ↑4 / ↓4 at their own rate, Q15 stopband: −72.8 / −73.9 / −70.4 / −78.1 dB at super_economy / economy / balanced / transparent.
    • At every divisor the matrix uses: 24 bit-pinned rows, Q15 stopbands from −70.9 to −74.7 dB at the 70 dB profiles.
    • Q31 within 1.9e−9 of double; float within 4.5e−8.
  • Emulated battery: M33 and M55 101/101; Hexagon 116/116. The band-4 bit pins hold on newlib and musl.
  • Ratchet: the icount gates pass on m33, m55, hexagon and host, with exceptions and again without exceptions or RTTI. The two builds agree within 0.001 %, so no row needed a midpoint.
  • Ceilings: ceilings.py measure passes for all three engines on all three targets.
  • Notebook: matrix.ipynb was re-executed in the pinned environment.
    • 728/728 pins reproduced.
    • 182/182 rows meet the promise: worst −72.31 dB at economy and −123.17 dB at transparent.
  • CI coverage of the new targets. No workflow needed an edit:
    • the icount ratchet builds everything with cmake --build build, and icount.py and ceilings.py discover the new targets by glob and by PROBE_SETS;
    • the host ratchet's sed matches tap_sr_*_hostcount_*, so it picks up the new host workloads.

Notes for the reviewer

  • Existing counts moved slightly. construct_q15_eco and down2_down2_q15_eco now count 14 fewer instructions on Arm and 8 fewer on Hexagon, because the relaxation table is two rows shorter. The by-2 probes measure 80 B less .rodata. All of this is inside the existing tolerances and ceilings, so nothing was re-recorded.
  • Ceilings were merged, not re-recorded. The new probe set's ceilings were recorded into a scratch file and only their keys were merged into ceilings.json. No existing ceiling was overwritten by --update.
  • Tests that used retired chains now use the new named chains. The tests of the chain machinery keep the mixed-ratio chains they need, spelled basic_chain<…>.
  • Band-4 stopband test. FixedPoint.FourthBandRelaxedQ15TablesStopbandsAreStated is named so that the existing Hexagon exclusion pattern already skips it. It is excluded by name on M33 and M55 too.
  • Not in this PR:
    • The version bump to 0.8.0 is X-b's.
    • The by_4 pointer in ratio.h is left for X-b.
    • rational_comparison.ipynb was not re-executed: it uses only the single-stage values 0, 1, 4 and 5, whose numbers did not change.
  • X-a4 as this PR leaves it (re-measured with the shipping generator):
    • 25 rows split per tier.
    • 7 chains are used only at transparent, including the four kept ones.
    • X-a4 adds three constants at 40–42, which makes CHAIN_END 43.

Generated by Claude Code

Decision 6 kept the single 4th-band stage out because two half-bands are
cheaper for x4 itself (43 against 61 MACs per output at economy, and they
still are). On X17's pins the 4th band's relaxed design is short (m = 4 at
divisors 2 to 4, m = 3 from 6 up), and at the high-rate end of every chain
by 8 and above it is the cheapest stage: 1/8 is down4 . down2 at 71 MACs
per output against 79 for three half-bands and 87 for v0.7's chain. The
maintainer amended decision 6 (docs/X4_X8_PLAN.md X3, X17).

The selection. matrix.py's FROZEN_SELECTION (X-a2's one-PR freeze) and its
frozen mode are gone, best_chain selects again, and band 4 is admitted
(NO_SINGLE_STAGE and its check removed). matrix.py diff against v0.17's
tables: 46 rows move at economy, 30 within the families and 16 across,
exactly X-a2's measurement; diff reports 0 after the regeneration. The
mean economy MAC/out over the 182 rows falls 87.76 -> 84.59 (-3.6 %).

The vocabulary and the names. up4 / down4 join ratio.h beside up8 /
down8. chain.h gains up2_up4, up3_up4, up2_up4_up2, up2_up3_up4,
up2_up4_up4, up3_up4_up4 and their mirrors; ten chains no row runs are
retired under D7 (their names and C constants in retired_words.txt as
exact names); up2_up6, up2_up8, down6_down2 and down8_down2 run no row at
economy but are kept, documented in chain.h, since X-a4's per-tier matrix
selects them at transparent.

The C ABI (X7: every value stable). New chains take 28 to 39; the retired
values 10, 11, 14, 15, 16, 21, 22, 25, 26, 27 are never reused and create
refuses them through a table; TAP_SR_RATIONAL_CHAIN_COUNT is retired for
TAP_SR_RATIONAL_CHAIN_END (40), the header listing the retired values.
create_stage takes 4/1 and 1/4 (the header says sixteen ratios), so the
cross rows with a single down 4 / up 4 beside bridge build through the
ABI. Tests pin CHAIN_END, every retired value refused, every live value
constructing in every format, and the 4th band accepted (the refusal pin
"(decision 6)" is gone). The ctypes binding maps names through an explicit
table. The exported symbol set is unchanged.

Regenerated through their generators: design.h's relaxation tables
(matrix.py pins: eight divisors from ten, 9 and 16 unused now, every
remaining pin unchanged), matrix_rows.h (matrix.py rows), PLAN.md 3.3-3.6
(matrix.py md), the scipy vectors (make_reference_vectors.py: up4, down4
and the chains up3_up4_up4, down4_down4_down3, down4_down2, up2_up4 for the
retired three; every other vector byte-identical), the coverage figure
(book_figures.py coverage-matrix, matplotlib 3.11.2 as before).

Band 4's fixed point: up4 / down4 rows in test_fixed_point.cpp's table at
every profile (up4's Q15 table is 4/3's; Q15 attained -72.8 / -73.9 / -70.4
dB at super_economy / economy / balanced, -78.1 at transparent; RMS from
double -90.7 ... -98.7 dBFS; Q31 within 1.9e-9), and its tables bit-pinned
at every divisor the matrix runs it at (2, 3, 4, 6, 8, 12, every profile,
24 rows) with their Q15 stopbands (-70.9 ... -74.7 dB at the 70 dB
profiles; a host suite, excluded on the QEMU legs). Every Q15 stage of the
vocabulary, up4 and down4 among them, attains the 70 dB tier at its own
rate, and every relaxed Q15 design too. Chain floors, footprints, the
non-finite reach and the chain tests move to the new chains (the chains
through the mixed ratios no row runs stay tested, spelled as basic_chain).

The ratchet: down4_down2_q15_eco, callmax_down4_float / _q15 and, at the
maintainer's direction, the host's down4_float_2ch / _12ch, recorded on
m33, m55, hexagon and host from the exceptions build (the two builds agree
within 0.001 % on every new row); every existing row of every engine is
unchanged in the baselines and gates in both builds (rational's
construct_q15_eco and down2_down2_q15_eco count 14 fewer instructions on
the Arm targets and 8 on Hexagon, the relaxation table's two missing rows;
bridge and async exact, checksums equal). A second probe set (up4 / down4,
tools/probe/probes.cmake SUFFIX, ceilings.py PROBE_SETS) has ceilings of
its own, recorded with --update and merged as <fmt>_by4; the by-2 probes'
.rodata and images measure 80 B below their record and are not
re-recorded. README icount and ceilings tables regenerated by their
scripts.

Decision 6's record, in the same PR: rational/PLAN.md (decision 6 amended,
R3, R16, section 1, 2.1, 3.1-3.4, the non-goal, the S1 ledger, section 6's
X-a3 record), rational/CLAUDE.md, rational/README.md (the quick start, the
C ABI, the footprint), ratio.h, test_ratio.cpp, the book (part7/charter.md,
chain.md, proof.md), docs/ROADMAP.md and tap_sr_rational_capi.h.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_016GKzq1VSdcMYCRMhddiMaf
Re-executed through the C ABIs in the pinned environment (Python 3.11,
requirements.lock) from rational/notebooks/: the rows are X-a3's, within-
family rows through the new chain constants and the binding's name table,
the cross rows that carry a single down 4 / up 4 beside bridge through
create_stage's 4th band. 728 of 728 (row, profile) pairs reproduce both
pins; 182 / 182 rows meet the promise at economy (worst candidate
-72.31 dB, passband 0.00478 dB) and transparent (-123.17 dB, 0.00001 dB).
Within a family the economy cost now runs 7.0 to 344.0 MACs per output
(7.7 to 371.0 before), the flagged rows' maximum 497.6 (514.5).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_016GKzq1VSdcMYCRMhddiMaf
…nts)

X-a2 marked done (SampleRateTap#109). X3 and section 8 record X-a3's
actual counts, which are X-a2's measurement exactly: 46 rows (30 within,
16 across), twelve chains added at C values 28 to 39, ten retired (10, 11,
14, 15, 16, 21, 22, 25, 26, 27), four kept for X-a4 (12, 13, 23, 24),
CHAIN_END 40 and 30 live values; the relaxation tables down to eight
divisors; the new ratchet rows (with the host's down4 rows the maintainer
asked for at X-a3) and the 4th-band probes' ceilings; the existing rows
unchanged in the files. X6's caveat gains the by-8 chain's Q15 counts.

X-a4's size as X-a3 leaves it, re-measured with the shipping generator
(best_chain at transparent against the committed economy chains): 25 rows
split per tier (17 within, 8 across), seven chains used only at
transparent, four of them X-a3's kept chains and three new
(up2_ratio3over2, up2_up6_up4, down4_down6_down2 at 40 to 42), CHAIN_END
43, 33 live values; unchanged from X-a2's scratch measurement.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_016GKzq1VSdcMYCRMhddiMaf
@tap
tap merged commit 3ec09aa into main Nov 21, 2026
41 checks passed
@tap
tap deleted the claude/sample-rate-solutions-comparison-mqc190 branch November 21, 2026 13:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants