Repository navigation
Project the softmax parametrization exactly onto the capped simplex each step - #1096
Merged
Merged
Conversation
…pped simplex
Each softmax step alternated a softmax-invariant renormalization with a
clamp to the ratio cap, for at most 32 rounds. Replace that loop with the
exact projection onto {w : sum(w) = total, w <= cap * d} in log space: one
common shift, then a clamp, with the shift found by active-set rounds (each
a lower bound that only adds records to the capped set) and finished by a
sort if they run long. The shift is computed in float64.
The selection receipt records softmax_in_loop_max_cap_ratio, the largest
ratio of a realized in-loop weight to its float64 cap before the closing
projection, in place of the exhaustion count. The projection parametrization
is untouched.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…scale cap-step launcher The tool's calibration summary and build manifest carry softmax_in_loop_max_cap_ratio in place of the exhaustion count. The sweep harness records each batch's selection receipt. exact_cap_modal.py runs one softmax configuration under the committed kernel and under microcosm#1078's 32-round loop, with the ratio at every forward pass, the cap step's rounds and its wall time. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…act-cap-projection
… projection Four Modal runs of the ACS local surface (1,588,854 households, 4,459 targets, a 5x cap, 800 epochs), at two softmax configurations whose earlier runs ran out of cap rounds, each under the committed projection and under microcosm#1078's 32-round loop (results/exact_cap.md, results/exact_cap/). The projection never ran out (one to three active-set rounds per step, 12.7-22.5 ms); the loop ran out on 705-713 of 800 steps (48.7-53.8 ms). The largest in-loop weight over its cap is 1 + 9.0e-6 under the projection and 1 + 8.7e-6 to 1.2e-5 under the loop. exact_cap_float32.py measures where that residual comes from and why the loop ran out; it runs on Modal from the sweep's volume. The solve.py change is the active-set comment, now citing those runs. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d loop ran out On full-scale vectors the exact projection had already put within their caps, microcosm#1078's loop still ran out of rounds in 10 of 12 trials: its shift is log(total) in float64 minus a float32 logsumexp, which bottoms out at log(total)'s float32 rounding residual (7.8e-8), and that lifts the 1-3 capped records with log caps below 2 in magnitude one float32 step over each round. With a float64 normalizer the projected vectors sit within 1 + 4.9e-7 of their caps; the float32 softmax's own total error (up to 8.2e-6 here) is the rest of the in-loop residual. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ests solve.py moves docs/calibration-l2-basis.md replaces the cap-rounds limitation with the projection, its tested invariants and the full-scale measurement; the experiment README adds the re-measurement; a changelog fragment records the change and the #1078 fragment drops its exhaustion-count claims. solve.py's bytes are attested by the US spec-engine seed protocol and the H1 calibrate parity case. Re-pinned on this tree: - EXPECTED_HASHES seed_protocol be39eb6b -> 5795dc07, seed_map 085d8d39 -> 292ad19c (build_inventory_coverage; tools/spec_engine_coverage.py --check: 41/41) - US spec_sha256 e0b757ce -> edcd6475 (docs/evidence/spec-engine/us-f0-coverage.json, test_us_multispine_pool_tool.py) - loader golden fee5893a -> 5135dd79 (test_spec_engine_loader.py) - calibrate parity pins (tools/graph_parity_repin.py calibrate; direct-call bytes unchanged) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brings main 4a36edc in by merge (base b7b4c29). Both sides moved the US seed protocol and seed map digests since the base, so the five pin files conflicted. The merge regenerates them for the merged tree with the repo's tools instead of taking either side's hash: - tools/repin_us_spec_engine_contracts.py rewrites EXPECTED_HASHES seed_map and seed_protocol, the loader golden and the multispine spec_sha256. Its first pass reads the stale pins and counts 40 of 41 inventory items covered, so a second pass restores 41; --check passes. - tools/spec_engine_coverage.py regenerates us-f0-coverage.json (--check: 42305/42305 fields, 41/41 inventory checks). The multispine pin equals the JSON's spec_sha256. - tools/graph_parity_repin.py calibrate re-pins the calibrate parity case; its direct.csv bytes did not move. same_edit.py 16ff6eb 4a36edc flagged nothing. In the engine-free venv, the pre-fix projection tests, test_l2_basis.py, the spec-engine inventory and loader tests, the graph parity pins and the ACS tool's two penalty tests pass on this tree (99 tests). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…w S2) The softmax cap step's two exits lifted every record that could reach its cap to that cap. The active-set rounds took that exit whenever rounding left no room after the capped records' caps, or no uncapped mass; the sort took it when no record met its test. Either way the total could end up to the uncapped records' caps over. A finite log-weight that underflows float64 also counted as no weight. _capped_log_shift now returns the current shift when the room is not positive: its lower bound keeps the room at least the uncapped records' share, so a room at or below zero is float64 rounding, and those records keep a rounding-sized share. When the uncapped weights sum below float64's normal range, the rounds hand over to _sorted_capped_log_shift. The sort sums weights in log space with logcumsumexp and includes every finite log-weight. When room_k is not positive it caps exactly the first k records, it clamps the answer to the previous record's cap shift so rounding cannot uncap that record, and it caps every record that carries weight only when their caps hold less than the total. _cap_every_record_shift is gone. The common path's arithmetic is unchanged. Invariants, each checked over up to 300 Hypothesis draws in test_softmax_cap_projection.py: the projection conserves the total to 1e-12 and respects every cap; zero weights and zero caps, drawn independently, stay at zero; it is idempotent and invariant to a constant added to the log-weights; a feasible input moves by the shift alone; it meets the KL projection's KKT conditions; it equals a 60-digit decimal water-fill; the rounds and the sort agree; and in float32 the realized weights stay within their caps to 1e-5. A new strategy lets the caps of a held set meet the total, or nearly, while the other records sit 45 to 1,100 nats below their caps. A verbatim, SHA-checked copy of the measured cap step (4bddde6, tests/fixtures/pre_cap_step_fix/) pins the new step bit for bit wherever the measured one settles in its rounds (review S1). The measured step fails 11 of the file's 19 tests; this one passes all 19. Six mutants of the new code each fail at least one test: the sort treating a non-positive room as +inf, the old all-capped exit, handing over only at zero uncapped mass, no previous-cap clamp, dropping underflowed records, and the no-k branch returning the lower bound. The repo's tools re-pin what the new solve.py bytes move: EXPECTED_HASHES seed_map and seed_protocol, us-f0-coverage.json (41/41 inventory checks), the loader golden, the multispine spec_sha256 (equal to the JSON's) and the calibrate H1 parity pins (direct.csv unchanged). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brings main 3a9c808 (#1484) in by merge. Both #1484 and this branch moved the US spec hash, so us-f0-coverage.json and the multispine spec_sha256 conflicted. The repo's tools regenerate both for the merged tree: tools/repin_us_spec_engine_contracts.py rewrites the multispine pin (--check passes), and tools/spec_engine_coverage.py rewrites the JSON (--check: 42210/42210 fields, 41/41 inventory checks). The pin equals the JSON's spec_sha256. This branch's seed protocol and seed map pins hold unchanged, and neither solve.py nor the calibrate parity pins moved. same_edit.py 8ae6934 3a9c808 flagged nothing. In the engine-free venv the projection, L2-basis, spec-engine inventory, loader and field-usage tests, the graph parity pin and H1 parity tests, and the ACS tool's eight penalty tests pass on this tree (129 tests). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brings main 3293730 (#1455, the emitter collector hostname) in by merge. It merged cleanly and touches no attested module or pin: the repinner's --check and tools/spec_engine_coverage.py --check (42210/42210 fields, 41/41 inventory checks) pass on this tree, and same_edit.py f86e9e1 3293730 flagged nothing. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…, N5) The measured-step differential holds only where every nonzero weight sits in float64's normal range: below it the current step hands its rounds over to the log-space sort, which the measured step lacked. The test docstrings and docs/calibration-l2-basis.md now say so, and the test docstring names the quantity that never fell more than 1% between passes: each forward pass's largest weight-to-cap ratio. N2: _IN_LOOP_CAP_TOLERANCE and the ACS tool test's matching bound say they hold for test sizes only; the release surface reached 1 + 9.0e-6. N4: the docs and the experiment README credit the float32 softmax only with the projected vectors' residual, the one exact_cap_float32.py decomposed. N5: the README scopes "the softmax results stand" to the two rerun configurations. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Merge main at 1e88319 (#1532), 1,016 commits past the merge base 3293730. Main has no commit on solve.py, the calibrate tests, the cap-step fixture or the exact-cap evidence, so the branch's 18 files that only it changed keep their bytes from 47c0625. docs/calibration-l2-basis.md, the experiment README and sweep.py, test_us_acs_local_release_tool.py and tools/build_us_acs_local_release.py merged on their own and carry the branch's edits unchanged. Five files conflicted. All five hold digests that a tool recomputes. Each was resolved by taking main's side and then running the tool: - docs/evidence/spec-engine/us-f0-coverage.json: main's side, rewritten by tools/spec_engine_coverage.py. - packages/microcosm-build/src/microcosm/build/spec_engine/inventory_coverage.py: main's EXPECTED_HASHES (source_manifest dc387988 kept), the branch's microcosm#1096 comment restored after main's last comment line, then seed_map and seed_protocol re-pinned by tools/repin_us_spec_engine_contracts.py. - packages/microcosm-build/tests/engine_free/shared/test_spec_engine_loader.py: main's golden and comment lines, the branch's microcosm#1096 line restored, then the golden re-pinned by the same repinner. - packages/microcosm-build/tests/engine_workflow/us/test_us_multispine_pool_tool.py: main's spec_sha256 and comment lines, the branch's microcosm#1096 line restored, then spec_sha256 re-pinned by the same repinner. - packages/microcosm-graph/tests/fixtures/parity/kernels/calibrate/pins.json: main's side, then re-pinned by tools/graph_parity_repin.py calibrate. Pins that moved, and the tool that wrote each: - EXPECTED_HASHES seed_map bcb012ed -> d216f75c and seed_protocol e1f88676 -> 2316aa41: tools/repin_us_spec_engine_contracts.py. - Minimal-loader golden spec_sha256 d5c303a4 -> eeba65f7: the same tool. - US multispine spec_sha256 3dabec5c -> c15471ae: the same tool. - us-f0-coverage.json, two map_sha256, two protocol_sha256 and two implementation_sha256 to the seed values above, and two spec_sha256 to c15471ae: tools/spec_engine_coverage.py (42394/42394 configuration fields; 41/41 inventory checks). - calibrate.adam@1 implementation_hash f6554bfe -> 19806a72 and node_key b6020102 -> c767438d on arm64/darwin/py3.14: tools/graph_parity_repin.py calibrate. direct.csv did not move. The repinner and the coverage tool each ran twice. The first repinner pass read stale pins and wrote covered_item_count 40 into test_spec_engine_coverage_tool.py; the second pass, after the coverage report was regenerated, restored 41, so that file equals main's. Both tools then passed --check. ruff format on the three repinned .py files changed the repinner's single quotes to double quotes and nothing else. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Main gained #1600, #1605, #1590, #1047, #1592, #1598 and #1545 since the 1e88319 this branch last merged. #1598 changed microcosm-calibrate (hierarchy value ranks) and an attested kernel module and regenerated the shared pins, so the five pin files conflicted. Each conflict hunk takes main's text, with this branch's #1096 comment sentence kept after main's, and the tools then wrote the values for the merged tree: - docs/evidence/spec-engine/us-f0-coverage.json: main's five hunks, then rewritten by tools/spec_engine_coverage.py (two map, two protocol, two implementation and two spec digests; 42394/42394 fields, 41/41 checks). - spec_engine/inventory_coverage.py: main's hunk and its hierarchy comment, plus the #1096 sentence; tools/repin_us_spec_engine_contracts.py wrote seed_map d29d95be and seed_protocol f3738669 (main: 0c19b903, 15e6cad1). - test_spec_engine_loader.py: main's hunk plus the #1096 comment line; the repinner wrote the golden 0b417bfc (main: 99f9b82e). - test_us_multispine_pool_tool.py: main's hunk plus the #1096 comment line; the repinner wrote spec_sha256 c79a1d3f (main: 98d58365). - parity/kernels/calibrate/pins.json: main's line, then tools/graph_parity_repin.py calibrate wrote implementation_hash 20180a24 and node_key 86ae2227 (main: 0c669ad2, fbab5f42). direct.csv, graph.json and inputs.csv did not move, so the default path's bytes are main's. The repinner and the coverage tool ran twice each, then both passed --check. ruff format changed only the quotes the repinner writes. tools/build_us_acs_local_release.py and its test merged without conflict. Main's #696 and this branch both changed do_package and _parse_args, in separate statements: main swapped the refresh recipe's staging value and added --block-ladder; this branch renamed one calibration key and reworded the --mass-parametrization help. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
_capped_log_shift hands its rounds to the log-space sort when the uncapped mass sums below float64's normal range, and its docstring said that every uncapped weight had then lost its precision. The converse does not hold: a sum still in the normal range can be made of subnormal terms. Where a million records share one subnormal weight the total ends 1.5e-11 off, past the 1e-12 the tests pin on up to 40 records. Handing over whenever one uncapped weight is subnormal does not fix that. The sort is 1.0e-11 off on the same input, and on a million distinct subnormal weights it is about 270 times worse than the float64 sum it would replace (9.9e-12 against 3.6e-14): logcumsumexp adds one record at a time and rounds each step at the spacing of a float64 near -700. So the code is unchanged and the claim is narrowed. The solver rounds log_w to float32 after every projection, up to 5e-7 in a weight, so no solve resolves any of this. solve.py changes in docstrings only. _capped_log_shift says what the hand-off is for and gains a precision note with two regimes: weights in the normal range (the total within 1e-13 by the rounds and 1e-11 by the sort on 1,588,854 records) and subnormal weights whose sum is still normal (up to about 2**-53 of the sum per term). _sorted_capped_log_shift and _project_softmax_log_weights_ point at it, and docs/calibration-l2-basis.md says the same. Two tests pin the note: one at the full-scale size with normal weights, one on the million-record case, which also fails if the step becomes more precise there and the figures go stale. solve.py's bytes are attested, so the same pins move again: tools/repin_us_spec_engine_contracts.py wrote seed_map 08a7dd1a, seed_protocol 46955c95, the loader golden b310bf3a and the multispine spec_sha256 eb2a8fe8; tools/spec_engine_coverage.py rewrote us-f0-coverage.json; tools/graph_parity_repin.py calibrate wrote implementation_hash 8496f213 and node_key f761929e. direct.csv did not move. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…eview R4) Before this branch a softmax solve's calibration_summary.json recorded softmax_cap_rounds_exhausted_epochs, a count of epochs; since, it records softmax_in_loop_max_cap_ratio, a weight-to-cap ratio. The ACS local-area tool's package stage copies the new key into the build manifest with dict.get, so a checkpoint calibrated by the old tool packaged with null there. Null is the value of a solve with no softmax cap step, and that checkpoint ran a capped softmax solve with the old step. The two receipts measure different things, so one cannot be turned into the other. do_package now refuses such a summary (the old key holds a value that is not null and the new key is absent) before any release directory exists. The message says the solve predates the exact cap step and how to calibrate again. A projection solve from before the change recorded the old key as null, and an older summary records neither key; both package as before. Tests: the refusal for a count of 713 and of 0, and four summaries that still package (old key null, new key with a ratio, new key null, both keys). docs/calibration-l2-basis.md and the changelog fragment describe the refusal, and the fragment says that every build's summary and manifest now name the new key, null under the default projection. No attested module changes, so no pin moves. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…pass) The note that 03035da added to _capped_log_shift gave its first regime as "every uncapped weight in float64's normal range" and said that on 1,588,854 records the sort leaves the total within 1e-11. That does not hold across the regime. With 1,588,854 uncapped weights 690 nats below the total, each 2.2e-300 and well inside the normal range, the sort ends 2.9e-11 off: its running log-space sum rounds once per record at the spacing of a float64 near -700, 1.1e-13. The rounding follows the size of the log and the record count, not normal against subnormal. The note now says that and pins three inputs in place of two regimes: weights the size a solve's are (log-weights 9 to 24 nats below the total's; rounds within 1e-13, sort within 1e-11), the same count 690 nats down (rounds within 1e-12, sort 2.9e-11 measured and pinned within 1e-9), and the million subnormal weights of the first pass. docs/calibration-l2-basis.md says the same. solve.py again changes in docstrings only (its syntax tree equals 6bb9c46's and d57d336's apart from docstrings), so no solve changes. One new test, test_normal_weights_far_below_the_total_cost_the_sort_digits, pins the second input with upper bounds only: the sort's rounding is a random walk there, so another platform draws another value. solve.py's bytes are attested, so the same pins move again: tools/repin_us_spec_engine_contracts.py wrote seed_map 5989ecc2, seed_protocol 23932edc, the loader golden e4557719 and the multispine spec_sha256 93dd4798; tools/spec_engine_coverage.py rewrote us-f0-coverage.json; tools/graph_parity_repin.py calibrate wrote implementation_hash 715d2a7a and node_key 589e1c6a. direct.csv did not move. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…und 1, finding 1) _sorted_capped_log_shift took log(room.clamp_min(float64 tiny)), so a positive room below float64's smallest normal value (2.2e-308) became that value and the shift and the projected total came out too large: 10% over at a total of 1e-308 and 1.2e-8 of itself over at 1e-300 on the review's inputs. Mask only the nonpositive rooms before the logarithm; the outer where still gives them a candidate of -inf. Tests: the review's two inputs through both entry points, a table of rooms across the subnormal range (three totals, one or two held records, one or five uncapped ones) and a property over drawn subnormal rooms, all against a 50-digit decimal bisection on the shift. The docstrings and docs/calibration-l2-basis.md say the sort takes the remainder's logarithm as it is. The default projection path is untouched. Pins follow in the next commit. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…w round 1, finding 1) The docstring of _capped_log_shift and docs/calibration-l2-basis.md said a remainder below float64's normal range comes only with an uncapped sum below it, so it always reaches the sort. That holds in exact arithmetic; float64 rounding can leave such a remainder to the active-set rounds (two records, one capped at its own weight and one at float64's smallest normal value, do it on 2,295 of 7,200 inputs). The rounds take math.log of the remainder as it is, so the answer is right either way. Both now say "up to rounding" and that the sort and the rounds both take the remainder's logarithm as it is. The rest rewraps two paragraphs left with short lines. No code changes; pins follow in the next commit. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… round 1, finding 1) solve.py's bytes feed the US seed protocol and the calibrate parity node, so the two commits before this one move their pins. Every value below was written by its tool; none by hand. tools/repin_us_spec_engine_contracts.py (two passes, then --check rc 0): - inventory_coverage.py seed_map 5989ecc2 -> cd5c2f2c, seed_protocol 23932edc -> 75891f4d - test_spec_engine_loader.py golden e4557719 -> a7b6a302 - test_us_multispine_pool_tool.py spec_sha256 93dd4798 -> b768e100 - test_spec_engine_coverage_tool.py: pass 1 moves its count, pass 2 restores it; no change. tools/spec_engine_coverage.py (two passes, then --check rc 0; 42394/42394 configuration fields, 41/41 inventory checks): us-f0-coverage.json's eight digest lines to match. tools/graph_parity_repin.py calibrate: pins.json implementation_hash 715d2a7a -> 1b3e2a71, node_key 589e1c6a -> f9472a28 (arm64/darwin/py3.14). direct.csv, graph.json and inputs.csv are byte-identical before and after and equal to main's. ruff format changed only the quotes the repinner writes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…, check P3-1 and P3-2) The section-8 tests of the softmax cap projection allowed 1e-11 of the total, at least 1e-319 at their totals, so a floor of 2**-1060 on the sort's remainder passed all 37 tests. Add a table and a property of rooms 1 to 64 steps wide at totals below 2**-1037, bounded at four steps per held cap plus 1e-9 of each weight, and a table of totals 1 to 7 steps wide that no positive cap reaches, bounded at 1e-9 of each weight with no absolute part. Reword the comment that gave the old floor's miss as an amount: 2**-1022 - room is an upper bound on it. Test code and comments only; no source file changes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A failure message read each weight back through float, which rounds a weight below one step of 2**-1074 to 0 or to 5e-324; print the decimal values instead. Name the step table's totals to three digits (1e-320, not 9.99989e-321), give the exp bound its stated reach (four steps per held cap hold for an exp three ulps off) and say the old floor raised only a remainder below 2**-1022. Test code and comments only. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Main gained #1612, #1596, #1603, #1601 and #1597 since the 68bbff7 this branch last merged (45 commits, 174 files). #1601 ("US: one copy of each shared helper") edited microcosm.calibrate.solve, an attested kernel module, and regenerated the shared pins, so the five pin files conflicted. No code or test file conflicted. Each conflict block takes main's text, with this branch's #1096 comment sentence kept after main's, and the tools then wrote the values for the merged tree: - docs/evidence/spec-engine/us-f0-coverage.json: main's five blocks (eight digest lines), then rewritten by tools/spec_engine_coverage.py (two map, two protocol, two implementation and two spec digests; 42395/42395 fields, 41/41 checks). - spec_engine/inventory_coverage.py: main's #1585 comment and digests, then the #1096 sentence after it; tools/repin_us_spec_engine_contracts.py wrote seed_map 8d0542f7 and seed_protocol 3ab23e82 (main: 270cf649, a696ad74; this branch before: cd5c2f2c, 75891f4d). - test_spec_engine_loader.py: main's digest line under the #1096 comment line; the repinner wrote the golden fac42090 (main: 1ff3b42c; branch: a7b6a302). - test_us_multispine_pool_tool.py: the #1096 comment line and main's digest line; the repinner wrote spec_sha256 fa75bd68 (main: bd526d8c; branch: b768e100). - parity/kernels/calibrate/pins.json: main's line, then tools/graph_parity_repin.py calibrate wrote implementation_hash 07e4330f and node_key 2972c813 (main: 018974ad, 30ad70b1; branch: 1b3e2a71, f9472a28). direct.csv, graph.json and inputs.csv did not move and equal main's, so the default path's bytes are main's. The repinner and the coverage tool ran twice each, then both passed --check; the repinner's first pass moved test_spec_engine_coverage_tool.py's count and its second restored main's. tools/ci_test_plan.py verify passes with main's 968 test files. ruff format changed only the quotes the repinner writes. solve.py merged without conflict. #1601 and this branch both changed calibrate: #1601 moved its option checks into _check_mass, _check_epochs_and_weight_ratio, _checked_l2_options and _check_l2_anchor_shape, and this branch rewrote the mass_parametrization paragraph of its docstring. The merged function has #1601's code and this branch's docstring. Every other definition is one side's alone: the merged file is main's plus exactly this branch's edit. #1601's new solve_constraint_system calls _optimize, which this branch changed, with the signature it still has; under mass_parametrization="softmax" it now runs the exact per-step projection. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
… (review round 2, P2) The refusal test checked for no package_result.json and no JSON under releases/, so a guard moved to just after release_dir.mkdir passed it: the refusal would leave an empty release directory, and packaging the checkpoint once it is calibrated again would stop at _new_release_dir. Assert that the release directory the package stage writes (RELEASE_DIR_PARTS under --out) does not exist. With the guard moved, both cases (713 and 0) now fail; the tool as it stands passes. Test code and a docstring only; no source file changes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
MaxGhenis
added a commit
that referenced
this pull request
Nov 15, 2026
#1096's exact softmax cap projection in solve moved the shared spec pins, so both conflicts were pin files. us-f0-coverage.json takes main's version and is regenerated by spec_engine_coverage.py. In test_us_multispine_pool_tool.py both pin comments are kept and the tools recompute spec_sha256 (fa75bd68 on main, 1e727e1c here). Repinned with the five-step sequence: repin --legacy-only, bundle generation, repin twice, coverage. Then: - repin, bundle and coverage --check: pass - ci_test_plan.py verify: pass - ruff check .: pass - county focused suite (-n 4): 746 passed, 1 skipped - spec-engine pin suites (-n 2): 116 passed - national pin suites (-n 2): 481 passed Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
MaxGhenis
added a commit
that referenced
this pull request
Nov 15, 2026
Main since 085672f: #1615 (the engine adapters read one year), #1618 and #1624 (reference documents trimmed to the keys their kernels read), #1096 (solve's exact softmax cap projection) and #1602 (Belgium Child rules bindings). None changes a file this branch changes except four pin files, where #1096 re-pinned the digests solve.py moves: - docs/evidence/spec-engine/us-f0-coverage.json (5 hunks) - spec_engine/inventory_coverage.py (seed_map, seed_protocol, source_manifest) - tests/engine_free/shared/test_spec_engine_loader.py (golden) - tests/engine_workflow/us/test_us_multispine_pool_tool.py (spec_sha256) Each hunk takes main's comment and values, with this branch's #776 comment lines after main's; then the tools write the values on the merged tree: - tools/repin_us_spec_engine_contracts.py: seed_map 2935a411..., seed_protocol e13541c1..., source_manifest ee208024... (this branch's value; main never moved it), loader golden 627e2563..., pool-tool spec_sha256 6fb922d2... (= the generator's printed digest). - tools/spec_engine_coverage.py: the same digests in us-f0-coverage.json; 42457/42457 fields, 41/41 inventory checks. - tools/generate_us_bundle_from_constants.py and tools/build_us_release_input_coverage_manifest.py rewrote nothing. ruff format on the three repinned .py files (quote style). Every --check mode (repinner, legacy repinner, coverage, generator, pool engine contracts), ci_test_plan verify, the manifest comparison and the transfer test's three contract digests agree with this tree. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
MaxGhenis
added a commit
that referenced
this pull request
Nov 15, 2026
Main gained 39 commits since 085672f, this branch's last merge: #1615 (US and UK build simulations stop at the year they read), #1618 and #1624 (reference documents trimmed to the keys their kernels read), #1096 (solve's opt-in softmax parametrization projects exactly onto the capped simplex) and #1602 (Belgium's Child rules bindings and Axiom input closure, still inactive). Four files conflicted, all of them pin files. Each conflicted hunk takes main's text, keeps this branch's comment sentences after main's, and leaves the value to the tools. - spec_engine/inventory_coverage.py, one hunk at seed_map and seed_protocol: main's three #1096 comment lines byte for byte, then this branch's three #1444 and #1453 lines byte for byte. - tests/engine_free/shared/test_spec_engine_loader.py, one hunk: main's #1096 comment line, then this branch's two #1453 lines, then the golden value. - tests/engine_workflow/us/test_us_multispine_pool_tool.py, one hunk: main's "attested bytes." line and its #1096 line, then this branch's #1453 sentence on two new lines (same words), then the spec_sha256. - docs/evidence/spec-engine/us-f0-coverage.json, five hunks, digests only, each to main's side. Git merged three other files that both sides changed: tools/build_us_fiscal_refresh_release.py, tests/engine_free/us/test_us_fiscal_refresh_builder.py and tests/engine_free/us/test_us_post_export_scoring.py. In each, every definition outside the pins was changed by one side, and the merged AST equals that side's. In the tool, main changed seven helpers (among them _dataset_from_frame and _materialize_base_simulation_columns) and this branch changed _main, _with_local_jurisdiction_flags and LOCAL_JURISDICTION_FLAG_SUPPORTS. The tool's imports hold main's us_dataset_through and this branch's local-jurisdiction import. Main touched no us_runtime module and no binding-identity list. Pins on the merged tree, each written by its tool: - tools/repin_us_spec_engine_contracts.py: seed_map 5230ab2f and seed_protocol 4ac422f9 in inventory_coverage.py; the golden 23b97b69 in shared/test_spec_engine_loader.py; the US spec_sha256 97f2b938 in engine_workflow test_us_multispine_pool_tool.py. Its covered_item_count in engine_contract test_spec_engine_coverage_tool.py ends at main's 41. - tools/spec_engine_coverage.py: us-f0-coverage.json (the seed map and protocol, the seed-stream implementation digest and spec_sha256, each twice); 42395/42395 configuration fields and 41/41 inventory checks. - Unmoved by the merge, as the coverage tool observes them again: full_checkpoint 47d4474d and the stacked pool's code digest 3c5e14be, this branch's values on lines main did not touch. tools/generate_us_bundle_from_constants.py --check reports the same US spec_sha256, 97f2b938. tools/repin_us_pool_engine_contracts.py --emit-json gives this branch's pinned manifest, 6e70bc74 over 1,059 rows. The release input coverage manifest built on the merged tree equals the committed one. The calibrate parity fixture (direct.csv, graph.json, inputs.csv, pins.json) has main's blob ids; this branch changes nothing under microcosm.calibrate. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
MaxGhenis
added a commit
that referenced
this pull request
Nov 16, 2026
main's #1096 (exact softmax cap projection in solve) and this branch's #1387 step both move the attested-source pins. The four conflicting pins keep both comments and were recomputed with the five-step repin: seed_map and seed_protocol, the loader golden vector, the pool tool's US bundle spec_sha256 (now 21710776...) and us-f0-coverage.json. Local verification on the merged tree: the three --check modes, ci_test_plan.py verify, ruff check . and git diff --check pass; focused ACS suites 828 passed, 1 skipped (-n 4); spec-engine pin suites 116 passed and national pin suites 481 passed (-n 2). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changes
Under
mass_parametrization="softmax", every Adam step ended on a loop: renormalize soexp(log_w)sums to the total, clamp to the ratio cap, repeat, for at most 32 rounds. This pull request replaces that loop with the Kullback-Leibler projection onto{w : sum(w) = total, w <= cap * d}in log space (_project_softmax_log_weights_insolve.py):log_w <- min(log_w + s, log cap), with one common shifts.s._capped_log_shiftruns active-set rounds, each one float64 pass over the records. WithCthe records already at their caps, the next shift solvessum(cap[C]) + exp(s) * sum(w[not C]) = total. That shift bounds the answer from below for everyC, soConly grows, and a round that adds no record ends the search. The rounds stop at the current shift when the capped records' caps already hold the total._sorted_capped_log_shiftfinishes with one sort over the remaining records, so the worst case costsO(n log n). The sort sums in log space, so a weight that underflows float64 still counts. The rounds also hand over to the sort when the uncapped weights sum below float64's normal range. Both paths take the logarithm of a positive remaindertotal - sum(cap[C])unchanged, so a remainder below that range still sets the shift.log_wto float32 after every projection, so no solve resolves these figures.options["iterate_selection_receipt"]["softmax_in_loop_max_cap_ratio"]records the largest ratio of a realized in-loop weight to its float64 cap, over every forward pass and the closing iterate, before the closing projection. It replacessoftmax_cap_rounds_exhausted_epochs.tools/build_us_acs_local_release.pyrenames that key incalibration_summary.jsonand in the build manifest's calibration block for every build. Under the default--mass-parametrization projectionthe tool writes null there, as it did under the old key.--stage packagenow refuses a summary that holds a count under the old key and lacks the new one. A softmax solve by the old loop wrote such a summary, and the two keys measure different things, so the tool cannot convert one to the other. The message says to run--stage calibrateagain without--resume. With--stage all --resume, the calibrate stage skips such a checkpoint as finished, and the refusal comes at package."projection"parametrization,_optimizenever calls the new step. Each line this pull request changes there either runs undersoftmax_massalone or sets a variable only that branch reads. At 1568979, the default solves still reproduceoptimizer_bda72cb02.pybit for bit in all seven cases oftest_defaults_reproduce_the_pre_change_optimizer_bytes, and the best-iterate oracle pins intest_solve.pystill pass. Outsidesolve.py, only the ACS local-area tool passesmass_parametrizationamong the packages and tools, and its flag defaults toprojection. No weight in a build with default settings changes.Invariants the tests hold
test_softmax_cap_projection.pychecks the projection on every input Hypothesis draws, 300 examples per property. The inputs include zero design weights (zero caps), a cap of 1 (the caps sum to the total), and totals from 5% to 100% of the caps' sum.sum(exp(P(x))) == total(rel 1e-12), andP(x) <= log cap. A record with zero weight or a zero cap stays at zero.P(P(x)) == P(x), and so does adding a constant to every log-weight first,P(x + c) == P(x).Decimalwater-fill written from the definition. The step agrees with itself when limited to 0, 1 or 2 active-set rounds before the sort. A 14-record chain that needs 12 rounds goes to the sort and matches the reference.total * softmax(log_w)sits within its float64 caps to 1e-5.In
test_l2_basis.py:1 + 1e-5for every capped softmax solve the two properties draw, and holdsNonewithout a cap. That includes caps of 1, 1.001 and 1.05, where the cap binds on nearly every record; at a cap of 1 the solve returns the design weights.In
test_us_acs_local_release_tool.py:--stage packagerefuses a summary with a count of 713 or 0 under the old key and no new key, and leaves no release directory. It packages a summary whose old key holds null, one with the new key (a ratio or null), and one with both keys, and each manifest carries the new key alone.Where items 1 to 8 compare weights, they use weight units (rtol 1e-9 and atol 1e-12 × total), not log units. When the caps nearly meet the total, the uncapped records hold a small remainder, and their float64 rounding amounts to a few ulps of the total: large in log space, small in weight space. Item 9 converts each weight's float64 log to a 50-digit decimal before taking its exponential, so a subnormal weight keeps its value in the comparison.
Full-scale measurement (Modal)
experiments/us-acs-local-l2-basis-20260928/exact_cap_modal.pyreran the ACS local release surface on Modal: 1,588,854 households, 4,459 targets, a 5x cap and 800 epochs. It used two configurations whose earlier runs ran out of rounds. Each ran under the new step and under a copy of the old loop in the script, and recorded the largest in-loop ratio at every forward pass (results/exact_cap.md):exact_cap_float32.pymoved a softmax run's final weights by a step-sized random perturbation and projected them, 12 times at full scale. The script realized them in float32, as the solve does: they reached 1 + 8.5e-6 of their caps, and the normalizer missed the total by up to 8.2e-6. With a float64 normalizer, the largest ratio fell to 1 + 4.9e-7 (results/exact_cap_float32.json). No run took the loop's overshoot apart this way.logsumexpfromlog(total)in float64, which bottoms out at the float32 rounding residual oflog(total)(7.8e-8). Each round, that shift lifts one to three capped records whose log caps fall below 2 in magnitude one float32 step over their caps. On vectors the projection had already settled, the loop still ran out in 10 of 12 trials.docs/calibration-l2-basis.mdreplaces its "known limitation" section with this account, and the experiment README adds it. The doc still recommends projection at that scale: softmax's training loss at λ = 0.03 exceeds projection's by 5%.Merges with main and re-pins
solve.py's bytes carry an attestation, so every edit to it, a docstring included, moves the same digests. A tool writes each one:EXPECTED_HASHESseed_mapandseed_protocol, the loader golden and the USspec_sha256:tools/repin_us_spec_engine_contracts.py.docs/evidence/spec-engine/us-f0-coverage.json:tools/spec_engine_coverage.py(41 of 41 inventory checks).implementation_hashandnode_key):tools/graph_parity_repin.py calibrate, and the direct call's bytes still equaldirect.csv.9a89cf8 merges main at 68bbff7, and 1568979 merges main at 085672f. In each, five files conflicted, and each of them holds digests that a tool recomputes. Both merges take main's text in every conflicted block, keep this branch's three comment sentences beside it, and let the tools write the values. Outside those five files, 1568979 equals git's own merge of its parents.
Main's public solve (#1601) also edited
solve.py, and that file merged without a conflict.calibrate, the one function both sides changed, carries main's body and this branch's docstring. Main's newsolve_constraint_systempassesmass_parametrizationto_optimize, so a softmax call through it runs the exact step; it records nosoftmax_in_loop_max_cap_ratio, and no test calls it with softmax.The fixture and the experiment README cite commit 4bddde6, so this lands as a merge commit, which keeps that commit in main's history.
What the reviews found
An independent review found that
_sorted_capped_log_shiftfloored a positive remainder at float64's smallest normal value, 2.2e-308, before taking its logarithm. Where the caps left less than that, the floor inflated the remainder. On the review's two inputs, the projected total came out 10% over at a total of 1e-308, and 1.2e-8 of itself over at 1e-300. Every testtest_softmax_cap_projection.pythen held passed under the floor._capped_log_shift's docstring anddocs/calibration-l2-basis.md: a remainder below the normal range reaches the sort only up to rounding, and the rounds also take its logarithm unchanged.solve.py's new bytes move, with the same three tools.On 4,000 random inputs whose remainders all stay in float64's normal range, the softmax step at 6544a01 returns f728a31's results bit for bit.
A second independent review, at 1568979, raised one P2 finding and none more severe. The package refusal test looked for JSON files alone, so it would pass a refusal that left an empty release directory, and the next package would stop on that directory. 2c49e27 makes the test assert that the refusal leaves no release directory.
Tests
At 1568979, on macOS arm64 under Python 3.14.7, one pytest process per file:
test_softmax_cap_projection.py54,test_l2_basis.py52,test_solve.py82,test_solve_constraint_system.py10,test_us_acs_local_release_tool.py314,test_bakeoff_us_support_mix_tool.py28,test_graph_parity_pins.py11,test_spec_engine_loader.py10, the engine-freetest_spec_engine_inventory_coverage.py13,test_spec_engine_seeds.py13 andtest_spec_engine_field_usage.py14. The skipped test needsMICROCOSM_US_CHRONICLE_FACTSset to the pinned consumer-facts feed.test_spec_engine_coverage_tool.py7, the engine-contract inventory test 2, and the one test intest_us_multispine_pool_tool.pythat holdsspec_sha256).tools/repin_us_spec_engine_contracts.py --check, with and without--legacy-only, andtools/spec_engine_coverage.py --checkexit 0.tools/ci_test_plan.py verifyreports ok over 968 test files.tools/graph_parity_repin.pyhas no check mode, so a script ran its repin with the write replaced by a comparison.pins.jsonmatched, and the direct call reproduceddirect.csv.ruff check .passes, and so doesruff format --checkonsolve.pyand the three re-pinned Python files. The projection test file passed both at 74238ac._sorted_capped_log_shiftat 74238ac, each in a copy of the source, against the projection tests:<for<=at the cap, for example) pass;expandlogresult by up to three ulps, a stand-in for other platforms' kernels. The first 15 tests went through those scripts at 6544a01, the other 17 at 74238ac.At 2c49e27, which edits
test_us_acs_local_release_tool.pyalone, under the same setup:tools/repin_us_spec_engine_contracts.py --checkexits 0 andtools/ci_test_plan.py verifyreports ok over 968 test files, so no pin moved.ruff checkandruff format --checkpass on the test file.release_dir.mkdirpasses the refusal test as it stood at 1568979 and fails both its cases at 2c49e27. An unchanged copy, loaded the same way, passes both.CI runs the full suites on the pushed head, on Linux.
solve.pycounts as shared code, sotools/ci_test_plan.py select-countriesturns on both countries. CI then runs lint, the engine-free suite on Python 3.13 and 3.14, the US and UK engine suites on both, UK integration, the wheel check and the installed-emitter check.axiom: n/a: calibration solver and release tooling; no policy rule changes.
🤖 Generated with Claude Code