Skip to content

[VARKA-345] Emit fdlibm's expm1 as IR nodes in the kernel, exact to StrictMath - #1629

Open
MaxGekk wants to merge 5 commits into
vecbricks:masterfrom
MaxGekk:varka-345c-expm1-r
Open

MaxGekk wants to merge 5 commits into
vecbricks:masterfrom
MaxGekk:varka-345c-expm1-r

Conversation

@MaxGekk

@MaxGekk MaxGekk commented Nov 22, 2026

Copy link
Copy Markdown

What changes were proposed in this pull request?

expm1 is the second function written on the PORT frame (#1609). PORT writes a math function as ordinary IR nodes inside the kernel, with no call at run time.

  • VarkaMathPort.expm1 expands fdlibm 5.3 s_expm1.c into IR nodes. They are node for node vfdlibm's Expm1.expm1Blended.
  • The C file has seven forms and some early returns. All of them are computed in every lane and blended in the C's order.
  • The range reduction is now one method, reduce. Both exp and expm1 call it.
  • VarkaMathPortSuite runs over a list of ported functions (exp and expm1). A new function is one new entry.
  • vfdlibm 0.2.0 is now pinned in sql/catalyst/pom.xml (it was 0.1.0, test scope).
Design details, the long words and the cap check

VarkaMathPort.expm1 expands fdlibm 5.3's s_expm1.c into ordinary IR nodes (lane arithmetic, compares, blends, the long bit views) inside the kernel's one method, node for node vfdlibm's Expm1.expm1Blended.
No call is made at run time.
The C's seven forms, chosen by the reduced exponent k, and its early returns (tiny, overflow, the non-finite lanes, x < -56 ln 2) are all computed in every lane and blended in the C's order.
So no lane is finished by a per-lane StrictMath.expm1.
The three planted faults of the sequence (a dropped correction term, a constant one ulp off, a moved threshold) are the package-private Fault argument exp already has, so the production expansion has none.

The range reduction k = (int)(invln2*x + 0.5 with x's sign), hi = x - k*ln2_hi, lo = k*ln2_lo is the same in e_exp.c and s_expm1.c.
So it is one method, reduce, that both expansions call. exp builds the same nodes as before.

The library keeps the C's int words in int lanes.
The kernel keeps them in long lanes, as exp does for its high-word tests.
The tests of k are long compares of k widened.
The words 0x3ff00000 - (0x200000 >> k) and (0x3ff - k) << 20 are long arithmetic. The first uses a logical shift, because AVX2 has no 64-bit arithmetic shift.
That these are the C's words on the lanes that read them is lemma L15 of the paired vfdlibm pull request. The proof is range arithmetic over every k the reduction gives.

VarkaMathPortSuite runs its tests over a list of ported functions (exp and expm1).
Each one has its expansion, its oracles, its fixed vectors and its sampled range.
The test-scope oracle moves from io.github.vecbricks:vfdlibm 0.1.0 to 0.2.0. This is the only change outside sql/catalyst/src and the plans.
Version 0.2.0 adds sinh, cosh and the inverse trigonometric ports, and splits Expm1 into a core and a rare mask.
VFdlibm.expm1 and Expm1.expm1Blended still give StrictMath's bits.

The auto chain cap of #1609 already admits a tree that holds the bit-view node, so no cap changes.
The suite asserts that the depth of expm1 is above the projection cap of 16 and within the port cap of 64.
Like exp, it is declined with the op cap's name (MAX_FUSED_NODES=64) in the form without a byte budget.

Why are the changes needed?

The exact default of the math family must match StrictMath bit for bit. sinh, cosh and tanh are built on expm1, so their ports wait for it.
A per-lane call is the only form that matches today. It costs the scalar call and keeps the surrounding vector code but not the function.
Written as IR, the sequence is vectorised.

Why the result is bit-identical

StrictMath.expm1 is fdlibm's s_expm1.c. Each step is one correctly rounded IEEE double operation.
A vector add, subtract, multiply or divide on a double lane is that same operation, so a lane that follows the C's path gets the C's bits.
Only the control flow differs.
Every form is computed in every lane, with k = 0 where the C does not reduce. This returns the C's inputs unchanged (L10 and L11 of vfdlibm's PROOFS.md).
The high-word tests are signed compares of the bits of |x|.
The blends are applied in the C's order, so the last blend that a lane satisfies is the C's return.

Does this PR introduce any user-facing change?

No. No compiler arm builds a port yet, so no SQL shape fuses with one and no answer moves.

How was this patch tested?

All on the laptop, with vfdlibm 0.2.0 as the oracle.

  • The head is e86bf16955b on master b4cbee926d1.
  • The push check and the extra gate ran on 3a18c3401e9. It differs from the head only by plan text.
    The push check on the head e86bf16 passes.
  • VarkaMathPortSuite (11 tests) passed, with 0 failed. It compares exp and expm1 with StrictMath, VFdlibm and the library's blended arm by raw bits.
  • The option-matrix arms ran on 50d4372, before the rebase onto master. 11 tests passed in each of seven arms.
  • Not verified: the width audit, AVX-512 hosts, and the speed against the per-lane call.
  • No proof file and no generated file changed, so proofs and regeneration did not run.
Full test record and what was not run

All on the laptop, with vfdlibm 0.2.0 as the oracle (checked on the test classpath).
The final runs below are on 3a18c34. The head e86bf16 differs from it by one plan paragraph.

VarkaMathPortSuite (its own JVM, 11 tests): 0 failed.
Both exp and expm1 are compared with StrictMath, VFdlibm and the library's blended arm by raw bits, NaN payloads included.
The sampled differential has four draws and 2^24 inputs a function. The range of expm1 is drawn over the forms of k.
The fixed vectors are each threshold of the C file and the edges of the forms of k, 64 neighbours each way in both signs, special values and eight NaN patterns.
They run at 2, 4 and 8 lanes over four null patterns and four lengths.
The suite also runs on the reference evaluator over each tree, catches each planted fault, and checks the depth, the decline at methodByteBudget 0, the constants' words and D2I.

The same suite also ran under the option matrix's arms cse=false, lanesOverride=4, lanesOverride=16, methodByteBudget=0, useAVX=2, maskFromWord=true and narrowLanes=false (dev/varka_matrix.sh --config ... --suites VarkaMathPortSuite): 11 tests passed in each arm.
These arms ran on the head before the final rebase onto master (50d4372). The rebase only brought four commits that do not touch the port or its suite.

dev/varka_push_check.py passes (572 counted lines of the cap of 1000). dev/lint-java is clean. VarkaInternalErrorSuite and VarkaProofFilesSuite pass (~/varka-ops/extra-gate.sh).
No proof file is touched, so dev/varka_prove.sh was not run. No generated file changes, so no regeneration.

The time of the suite is predicted and scored in VARKA-345.md (345c). The prediction was under 3 times exp alone (46.9 s).
The two runs on the laptop took 86.5 s and, on the final head with the machine shared, 175.1 s. The prediction held in one and failed in the other.
The cost is not established. It is owed a timing on an idle machine or on the runners.

The speed of the port against the per-lane call is not measured here. The per-lane form is row 356's, and the runners are dispatched separately.
The width audit and AVX-512 hosts were not verified.

Review

/code-review high (one round, on 8bed348) found one real bug. It is fixed, but the fixes were not reviewed again. The paired vfdlibm pull request (branch varka-expm1-long-words, lemma L15) is not opened yet. The size is 572 counted lines. The cherry-picked commit 500a049720e keeps an Opus trailer.

The finding, the other fixes and the commit trailer

/code-review high (one round, on 8bed348): 1 important finding, fixed.
The suite computed the library's blended arm and dropped its result, so the third oracle was never compared. It is compared now.
Four nits are also fixed: the sampled range of expm1 covered the middle forms of k for about 5% of one draw, and three plan statements were wrong (the oracle version, a date, a missing cost prediction).
The fixes (50d4372, rebased) were not reviewed again.

The paired vfdlibm change (L15, a proof and its hinge test; no code) is a separate pull request on the branch varka-expm1-long-words. It is not opened yet.
The size is 572 counted lines of the cap of 1000.
The cherry-picked commit 500a049 keeps an Opus trailer.

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

Generated-by: Claude Code (Claude Sonnet 5.5)

t added 5 commits November 22, 2026 16:02
…trictMath

The PORT form's second function on 345b's frame: s_expm1.c's seven forms
and early returns computed in every lane and blended, node for node
vfdlibm's Expm1.expm1Blended, with the C's int words in long lanes. The
reduction is shared with exp. VarkaMathPortSuite runs its tests over the
list of ported functions, so expm1 gets the sampled differential, the
fixed vectors, the reference evaluator, the depth caps and the planted
faults.

Generated-by: Claude Code (Claude Opus 5.5)
The test-scope oracle moves from 0.1.0 to 0.2.0. VFdlibm.expm1 and the
Expm1 blended arm the port suite reads give the same bits; 0.2.0 adds
sinh, cosh and the inverse trigonometric ports and splits expm1 into a
core and a rare mask without moving a result.

Generated-by: Claude Code (Claude Sonnet 5.5)
Generated-by: Claude Code (Claude Sonnet 5.5)
…ange by k's forms

The port suite computed the library's blended arm and dropped its result, so
the third oracle was never checked. The suite now returns it, and the sampled
range of expm1 covers the forms of k. The plan names the 0.2.0 oracle.

Generated-by: Claude Code (Claude Sonnet 5.5)
Generated-by: Claude Code (Claude Sonnet 5.5)
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