Skip to content

[VFDLIBM] Prove expm1's words in long lanes, the form Varka's kernel emits - #133

Merged
MaxGekk merged 3 commits into
mainfrom
varka-expm1-long-words
Nov 22, 2026
Merged

MaxGekk merged 3 commits into
mainfrom
varka-expm1-long-words

Conversation

@MaxGekk

@MaxGekk MaxGekk commented Nov 22, 2026 •

Copy link
Copy Markdown
Contributor

What changes were proposed in this pull request?

This PR adds lemma L15 to PROOFS.md and its tests in ProofsTest (l15ThresholdsAreTheCs, l15LongWordsAreExpm1sInts, l15ExponentAddIsTheCsHighWordAdd, l15MasksKeepEachWordOnItsLanes).
The library code does not change, except for comment pointers to L15 in Expm1.java and Lanes.java.
Varka's emitted expm1 kernel keeps the C's int words in long lanes, as Log does (L8).
L15 proves that these long words equal the C's int words on the lanes that read them.

The paired Varka PR, the statement of L15 and the proof

The paired Varka pull request is vecbricks/varka "Emit fdlibm's expm1 as IR nodes in the kernel, exact to StrictMath".
Its kernel computes the operations of Expm1.expm1Blended with the C's int words held in long lanes, the way Log does (L8).
A kernel's high-word tests are L3's compares of the bits of |x|, and its k is a long widened from an int.
The doubles are the same operations in the same order, so L15 covers only the words.

L15 states five facts about a lane whose form reads the words.
The long 0x3ff00000 - (0x200000 >>> k) (for 2 <= k < 20) is the C's int word widened.
The long (0x3ff - k) << 20 (for 20 <= k <= 56) is the C's int word widened.
w << 32 is the bits of the double whose high word is the C's word and whose low word is 0.
The compares of k are the C's.
bits(y) + (k << 52) is the C's __HI(y) += (k<<20): the low word kept, the high word the int sum modulo 2^32.
This last fact is Expm1's own code too.

The proof is range arithmetic.
0x200000 >> k is positive and below 2^20 for 2 <= k < 20, so the arithmetic and the logical shift agree.
(0x3ff - k) << 20 stays in [0x3c700000, 0x3eb00000], below 2^31, so no int overflows.
A word on a lane that does not read it is never kept (hypothesis H16).
The two shifts do differ there, at k = 40, so the hypothesis is needed.
l15MasksKeepEachWordOnItsLanes checks H16 on Expm1's own masks: Expm1.expm1Blended against StrictMath at every k from -56 to 1024, with the forms mixed in a vector.
H17 bounds k to -56..1024 from L10's domain, and the test asserts the two end doubles.
That Varka's kernel uses these masks with long words is checked in Varka's VarkaMathPortSuite (vecbricks/varka PR #1629, 2^24 sampled inputs).

The change is rebased on main after the 0.2.0 release.
L12, L13 and L14 were taken since the branch was cut, so the lemma is L15.

Why are the changes needed?

The Varka kernel writes expm1 with long words.
"Same result, proven" (AGENTS.md) asks for a numbered lemma for any form that departs from the C's int words.
Without L15 the kernel's long words rest on an unwritten argument.

Does this PR introduce any user-facing change?

No.
Only PROOFS.md, tests and code comments (three in two files) change.
No public method, result or requirement moves, so CHANGELOG.md has no line.

How was this patch tested?

mvn -B verify on the head (8432563): BUILD SUCCESS, 701 tests, 0 failures, 0 errors, 0 skipped, in 4 min 28 s.
ProofsTest runs 43 tests, the four L15 tests among them.
A wrong mask is caught: blending the mid word over k == 40 failed l15MasksKeepEachWordOnItsLanes at every width (7 of 7569 inputs), and so did keeping the high word on the far lanes (7163 of 7569); both mutations were made by hand and reverted.

Not run: dev/prove.sh, dev/jar-check.sh and any benchmark.
No .smt2 file changed and z3 is not installed here, so prove.sh has nothing to check.
Only comments changed in the main sources, so jar-check.sh has nothing new to check.
Nothing here is a speed claim, so no benchmark.

/code-review high before 4162621 found 7 items: 2 important, 5 nits.
I fixed 3 and stated one limit of the test in PROOFS.md.
I left 3 nits open.
The /code-review high comment on 4162621 (1 important, 4 nits) is addressed in 8432563: a vector test checks H16 on Expm1's masks, L15 names Varka's VarkaMathPortSuite as its kernel check, the loop uses the C's 56 and 20, L15 adds the __HI(y) += (k<<20) step with a test, and the Encoding now calls the check a Java loop and takes the bounds on k from L10's domain (H17).
8432563 itself has not been reviewed.

Test setup, the review items and what changed

The mvn -B verify run used origin/main at 71c7b9e as base, vfdlibm 0.2.1-SNAPSHOT, JDK 25.0.5.1, on this laptop.
Earlier runs gave BUILD SUCCESS with 695 tests, 0 failures, 0 errors, 0 skipped: on 699a011 in 8 min 20 s, on 4162621 in 4 min 26 s.

The two important items:

  • A stray "Encoding" paragraph sat at the end of PROOFS.md, after the atan2 section. I deleted it.
  • The test recomputed the masks and words from literals, so it could not fail if Expm1's code changed a mask. The second review raised this again; l15MasksKeepEachWordOnItsLanes now checks it.

The nits:

  • Fixed: the proof's range for (0x3ff - k) << 20 had the wrong low end. The right range is [0x3c7, 0x3eb] and [0x3c700000, 0x3eb00000].
  • Fixed: the Encoding paragraph cited the wrong bound for k. It now gives -56 <= k <= 1024 as H17, from L10's domain.
  • Open: L15 sits between L11 and L12 so it stays with the expm1 lemmas, which leaves the numbers out of order.
  • Open, in the paired Varka branch and not in this one: sampling of the far form in VarkaMathPortSuite, and a reflection lookup in its static initializers.

Was this patch authored or co-authored using generative AI tooling?

Generated-by: Claude Code (Claude Sonnet 5.5, Claude Opus 5.5)

Max Gekk added 2 commits November 22, 2026 15:35
Varka's PORT expansion of expm1 (VarkaMathPort.expm1) holds s_expm1.c's
int words in long lanes, as Log does (L8). L15 proves the long words and
tests are the C's ints on the lanes that read them, and
ProofsTest.l15LongWordsAreExpm1sInts checks every k from -1100 to 1100.

Generated-by: Claude Code (Claude Opus 5.5)
Generated-by: Claude Code (Claude Sonnet 5.5)
@MaxGekk

MaxGekk commented Nov 22, 2026

Copy link
Copy Markdown
Contributor Author

Review at code-review high on head 4162621: one important finding and four nits.

Important

  • src/test/java/io/github/vecbricks/vfdlibm/ProofsTest.java:918: the L15 hinge test does not check H16, the hypothesis the lemma rests on. The final assertNotEquals only shows that int and long shifts differ at k = 40. It never checks that Expm1's masks keep a word only on the lanes that read it, and the lemma's Encoding paragraph says so ("The test does not check H16 itself"). If the blend kept midWord on a k = 40 lane, the test would still pass, against the rule that a hinge test must fail when a hinge is false. Fix: a test that runs the blend at each k form and fails when a word is kept on a lane that does not read it, or state H16 as covered only by Varka's vector tie.

Nits

  • PROOFS.md:742: L15 covers Varka's emitted VarkaMathPort.expm1 kernel, not code in this repository. Expm1 keeps its words in IntVector lanes, no source file carries a PROOFS.md, L15 pointer, and the vector tie (VarkaMathPortSuite, 2^24 sampled inputs) lives in Varka. Add a pointer, or say where the check lives so it can be run.
  • ProofsTest.java:893: most of the loop cannot fail. The far and mid assertions compare one expression on an int and on its widening. The !mid && !high branch repeats a k-independent assertion about 2,000 times. The bounds come from Expm1.K_FAR and K_SPLIT instead of the C's 56 and 20, so a moved threshold moves the expectations with it. The k == 1, -1 and 0 compares are never exercised.
  • PROOFS.md:761: the C's __HI(y) += (k<<20) is not covered. Its long form, yBits + (kLong << 52) with the carry, is argued only in a code comment in Expm1.java. Add it to L15's Statement, Proof and test, or cite the lemma that covers it.
  • PROOFS.md:777: "checked exhaustively ... -56 <= k <= 1024" rests on L10's bounds on k, which the test does not re-derive. It is a Java loop, not a machine-checked file, so Encoding "None" plus "exhaustive" reads too strong. Say it is a Java loop and cite L10.

Generated-by: Claude Code (Opus 5.5)

Address the review of 4162621. L15's new vector test runs Expm1.expm1Blended
against StrictMath at every k from -56 to 1024, forms mixed in a vector, so a
mask that keeps a word on a lane whose form does not read it fails. The scalar
loop now takes the C's literal 56 and 20, checks each word's double against
1-2^-k or 2^-k, and a separate test pins K_FAR and K_SPLIT. L15 gains part (d),
the C's __HI(y) += (k<<20) as the long add of k << 52, with its own test, and
H17, the bounds on k from L10's domain. L15 now says it covers Varka's emitted
kernel, checked in Varka's VarkaMathPortSuite, and Expm1 and Lanes point to it.

Generated-by: Claude Code (Claude Opus 5.5)
@MaxGekk

MaxGekk commented Nov 22, 2026

Copy link
Copy Markdown
Contributor Author

Addressed in 8432563. Only comments change in the library code.

Important: H16 is now tested.
The new test l15MasksKeepEachWordOnItsLanes runs Expm1.expm1Blended against StrictMath.expm1 by raw bits, at every width, on 7569 inputs that cover every k from -56 to 1024.
It fails when a word is kept on a lane that does not read it.
I checked this with two mask errors made by hand and then reverted:

  • The mid word blended over k == 40 fails 7 inputs at all four widths.
  • The high word kept on far lanes (high.or(far)) fails 7163 inputs at all four widths.

There is one known gap.
On a far lane with k mod 32 >= 22, the int mid word is the same as one's word, so a mistake there would pass.
L15 and the test's Javadoc say so.

Nits

  • Where the check lives: L15 now says it covers Varka's emitted VarkaMathPort.expm1, not code in this repository. It names the vector tie in Varka: VarkaMathPortSuite, 2^24 sampled inputs, [VARKA-345] Emit fdlibm's expm1 as IR nodes in the kernel, exact to StrictMath varka#1629. PROOFS.md, L15 pointers are added in the Expm1 class Javadoc, the __HI(y) comment and Lanes.addExponent.
  • Loop assertions: the loop now uses the C's literal 56 and 20. A separate test l15ThresholdsAreTheCs checks K_FAR == 56 and K_SPLIT == 20. The k-independent assertion is moved out of the loop. k == 1, -1 and 0 run through the vector test above, on the real masks. An int-versus-widened-long compare cannot fail, and L15 says that.
  • __HI(y) += (k<<20): no lemma covered it, so it is now part (d) of L15's Statement and Proof. The new test l15ExponentAddIsTheCsHighWordAdd checks k from -1100 to 1100 against 1024 bit patterns, including high words that wrap either way.
  • "Exhaustive": the Encoding now calls the check a Java loop. A new hypothesis H17 takes -56 <= k <= 1024 from L10.

mvn -B verify: BUILD SUCCESS, 701 tests, 0 failures, 0 errors, 0 skipped (ProofsTest 37 to 43).
8432563 itself has not had a review yet.

Generated-by: Claude Code (Claude Opus 5.5)

@MaxGekk
MaxGekk merged commit 17659d0 into main Nov 22, 2026
14 checks passed
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.

1 participant