fdlibm on the Java Vector API: math functions over DoubleVector lanes whose every lane is
bit-identical to java.lang.StrictMath, but for a two-NaN lane of atan2.
Status: 0.x. exp, expm1, log, log1p, log10, sinh, cosh, asin, atan, acos
and atan2 are ported and released in 0.2.0 (exp, expm1, log, log1p and log10 in
0.1.0), as io.github.vecbricks:vfdlibm. Functions are added one at a time, as
Varka needs them. A minor version may break the API and a
patch may not; adding a function is a patch. Bit identity with StrictMath is the contract, and
no version changes it (CHANGELOG.md); the one lane it excepts is a lane of two NaNs with
different bits in atan2.
A client that depends on the released jar, from Maven Central. Its pom.xml:
<project xmlns="http://maven.apache.org/POM/4.0.0">
<modelVersion>4.0.0</modelVersion>
<groupId>example</groupId>
<artifactId>client</artifactId>
<version>1</version>
<properties>
<maven.compiler.release>25</maven.compiler.release>
</properties>
<dependencies>
<dependency>
<groupId>io.github.vecbricks</groupId>
<artifactId>vfdlibm</artifactId>
<version>0.1.0</version>
</dependency>
</dependencies>
</project>and src/main/java/example/Main.java, which calls VFdlibm.exp on the lanes of an array, in
both forms (f(x) and f(x, live)), and compares with StrictMath:
package example;
import io.github.vecbricks.vfdlibm.VFdlibm;
import jdk.incubator.vector.DoubleVector;
import jdk.incubator.vector.VectorMask;
import jdk.incubator.vector.VectorSpecies;
public final class Main {
private static final VectorSpecies<Double> SPECIES = DoubleVector.SPECIES_PREFERRED;
public static void main(String[] args) {
double[] xs = {0.5, 1.0, 2.0, -1.0, 10.0, 700.0, 710.0, Double.NaN, 0.0, -0.0, 1e-300, 3.5};
double[] ys = new double[xs.length];
int i = 0;
for (; i < SPECIES.loopBound(xs.length); i += SPECIES.length()) {
VFdlibm.exp(DoubleVector.fromArray(SPECIES, xs, i)).intoArray(ys, i);
}
for (; i < xs.length; i++) { // the tail the species does not fill, one lane at a time
ys[i] = StrictMath.exp(xs[i]);
}
boolean same = true;
for (int k = 0; k < SPECIES.loopBound(xs.length); k++) { // the lanes VFdlibm computed
long got = Double.doubleToRawLongBits(ys[k]);
same &= got == Double.doubleToRawLongBits(StrictMath.exp(xs[k]));
}
System.out.println("exp(" + xs[0] + ") = " + ys[0] + " at " + SPECIES.vectorBitSize()
+ " bits; the computed lanes have StrictMath's bits: " + same);
// Only the lanes set in the mask are computed; the others keep the input's bits.
DoubleVector x = DoubleVector.fromArray(SPECIES, xs, 0, SPECIES.indexInRange(0, xs.length));
VectorMask<Double> live = VectorMask.fromLong(SPECIES, 0b1);
DoubleVector z = VFdlibm.exp(x, live);
System.out.println("masked: lane 0 is " + z.lane(0) + ", lane 1 is " + z.lane(1));
}
}The Vector API is still incubating, and the JVM does not resolve an incubating module unless it
is told to, so at run time a client adds the module: --add-modules jdk.incubator.vector
on the class path, as here (without it the run fails with NoClassDefFoundError: jdk/incubator/vector/DoubleVector; on the JDK this was checked with, 25.0.5, a plain javac
needed no flag for a class-path build, and passing it there is harmless). The example assumes
the host's preferred species is 128 bits or more, which the library requires of every vector
it is given. The class path comes from Maven:
mvn -q compile org.apache.maven.plugins:maven-dependency-plugin:3.7.0:build-classpath \
-Dmdep.outputFile=cp.txt
java --add-modules jdk.incubator.vector -cp "target/classes:$(cat cp.txt)" example.Mainwhich prints, on a host with 512-bit vectors (the width is the host's), and the JVM's own warning that an incubator module is in use:
exp(0.5) = 1.6487212707001282 at 512 bits; the computed lanes have StrictMath's bits: true
masked: lane 0 is 1.6487212707001282, lane 1 is 1.0
On the module path, the client names the module instead of passing the flag: a
src/main/java/module-info.java that requires the jar's module,
io.github.vecbricks.vfdlibm, and the Vector API's:
module example {
requires io.github.vecbricks.vfdlibm;
requires jdk.incubator.vector;
}built and run with no --add-modules at all (without the second requires, javac says that
the package jdk.incubator.vector is not visible):
mvn -q clean compile org.apache.maven.plugins:maven-dependency-plugin:3.7.0:build-classpath \
-Dmdep.outputFile=cp.txt
java --module-path "target/classes:$(cat cp.txt)" -m example/example.MainEach function takes a vector of any species of 128 bits or more. Released in 0.2.0: exp,
expm1, log, log10, log1p, sinh, cosh, asin, atan, acos and atan2(y, x), which
takes two vectors. The system property vfdlibm.fault plants a
fault, for this project's tests only, and works in the shipped jar too: never set it, including
through JAVA_TOOL_OPTIONS; a JVM that has it set prints a warning to System.err once. The
property and the fault names are for this
project's tests only: they are not part of the public API or of the compatibility promise, and
any release, a patch included, may rename or remove them. With the property unset, the results
are unchanged, and each lane still meets the contract below.
Which species to pass. Every species of 128 bits or more gives the same bits; what the body
allocates differs. The allocation check (bench/alloc-check.py, run by CI) covers 256 bits, the
preferred species and SPECIES_MAX (up to eight lanes) on x86, and the preferred species, 128
bits, on GitHub's Arm runner. The files under bench/results/ read as allocating, and the check
does not cover: exp and log at 128 bits on x86, and every function at 512 bits on an AVX2
host. SPECIES_MAX was read on a laptop only (max-finish-alloc-free-laptop-2026-11-21.txt); the
host files that have a *Max row (the Xeon's of 21 November for all five functions, the EPYC's of
20 November for exp and log10, and exp-onediv-xeon8573c-2026-11-03.txt) read the old finish.
The Javadoc of VFdlibm gives each reading with its file, and lists what is not measured: the
speed of 512 bits against 256 on the EPYC 9V74 draws that have AVX-512, and any port's speed on
Arm.
0.2.x supports JDK 25 only. The Vector API is incubating, and its API and C2's lowering of
it move between JDK releases, so what a newer JDK does with these functions has not been
measured here. The contract, bit identity with StrictMath, is tested on JDK 25 and on no
other: every CI row, the nightly sweep and the benchmarks run Zulu 25. The example above is run
as written, on JDK 25, every week by .github/workflows/readme-check.yml, with the version of
its dependency replaced by the latest release on Central.
StrictMath is specified as fdlibm's results, the same on every host, and Apache Spark computes
exp, log, pow and their relatives with it. The Vector API's own math operators
(VectorOperators.EXP and the others) call SVML or SLEEF. Those are accurate to about one unit in
the last place, but they are not fdlibm, so their lanes can differ from StrictMath in the last
bit. A vectorized engine that must return exactly what the JVM's scalar code returns needs
fdlibm's own sequence of operations, lane by lane. That is this library.
- Bit identity. For every
doubleinput, each lane equalsStrictMath.fon that input, compared byDouble.doubleToRawLongBits. NaN payloads and signed zeros are included. For a function of two arguments (atan2,pow,hypot), a lane where both arguments are NaN with different bits equals one of the two arguments' bits with the quiet bit set (forhypot, the same with the sign bit cleared); which one is not specified, sinceStrictMath's own choice varies. - fdlibm's operations, in fdlibm's order. Only IEEE
+ - * /,sqrtand bit operations. There is no fused multiply-add and no reassociation, so the rounding of every step is fdlibm's. - Rare paths, exact too. Lanes on a rare path (huge arguments, subnormals, special cases) are
either computed in the vector, every branch blended (in every vector, or only in a vector that
holds a rare lane), or finished by
StrictMathper lane; the result is exact either way. The choice is made per function from benchmarks, and stays provisional.exp,expm1,log,log10andlog1peach have files from the Xeon Platinum 8573C and the EPYC 7763 (bench/results/), and each file's reading is inSKILLS.md; where two arms are within 1.3x of each other no direction is read, and where the hosts disagree the files say so. The decision waits for a second run of the 8573C and a first of the other AVX-512 hosts (HARDWARE.md, the EPYC 9V45 when drawn), a pair, and the rules for a tie and for hosts that disagree (issue #30). The laptop's numbers do not agree at every width.
Each function is checked against StrictMath on the same JVM:
- exhaustively where a range is small enough;
- by sampled bit patterns over the whole domain;
- with fdlibm's thresholds and the known hard cases as fixed vectors;
- every night (
.github/workflows/nightly.yml), by a sweep of all 2^32 high words, three low words each (of one argument a night for a function of two arguments, the two alternating by default:pair-passes), and by fuzzing from a fresh seed, every arm at every width the runner has; x86's 128 bits, which run lane by lane there, are swept a 1/32 slice a night, and Arm's 128 bits whole every night (SKILLS.md, "The nightly sweep and fuzz").
Apache-2.0. The functions port Sun's fdlibm 5.3 C sources, whose notice NOTICE preserves. They
are never translated from OpenJDK's FdLibm.java, which is GPLv2 with the Classpath exception;
StrictMath is used only as the oracle the tests compare against.