Jafama (Java Fast Math) is a Java library aiming at providing faster versions of java.lang.Math treatments, at the eventual cost of 1e-15ish accuracy errors but still handling special cases properly (NaN, +-Infinity, ties, etc.). It also provides additional features, such as angles normalization methods, inverse hyperbolic trigonometry, etc.

License

Apache License V2.0

Current external dependencies

• src/main:

  • Java 5+

• src/test:

  • Java 6+
  • JUnit 3.8.1

• src/build:

  • Java 6+

Principal classes

• FastMath, which corresponds to Math API, plus additional treatments.

• StrictFastMath, which is a strict version of FastMath (and not a fast version of StrictMath, which would rather be called FastStrictMath), through delegation to StrictMath (instead of Math) and use of strictfp.

• NumbersUtils, which contains very low level number-related treatments, and is used by (Strict)FastMath.

Principal additional features, that are not found in Math

• Angles normalization methods (normalizeXxx), derived from those used in java.lang.Math, for which, sadly, no API is provided, letting most users struggle with their own implementations.

• Direct or inverse hyperbolic trigonometry (coshm1, asinh, acosh, acosh1p, atanh, etc.).

• A 3D hypot.

• A remainder(...) method, that unlike Math.remainderIEEE(...), returns a value that is the closest to the dividend, and has the same sign, which is more consistent across values (doesn't depend on whether values are even or odd), with intuition, and with how modulo operator (%) behaves.

• Various floor/ceiling/rounding/modulo related functions.

• (Strict)FastMath.PI_SUP, which is the closest double value superior to mathematical Pi, such as 2PI_SUP angular span fully covers the trigonometric circle (2Math.PI doesn't).

Miscellaneous

• Methods with same signature than Math ones, are meant to return "good" approximations on all range. Methods terminating with "Fast" are meant to return "good" approximation on a reduced range only. Methods terminating with "Quick" are meant to be quick, but do not return a good approximation, and might only work on a reduced range.

• Non-redefined methods Math methods (up to some version of the JDK) are also available, for easy replacement, even though for some of them, such as for incrementExact, you might want to stick to Math versions to benefit from eventual JVM intrinsics.

• For performances reasons (for example if wanting to run with no GC), these treatments do not (unless delegating to JDK) generate objects at run time.

• Trigonometric treatments make use of look-up tables: around 1 Mo total, and initialized lazily and independently, or on first call to (Strict)FastMath.initTables().

• Depending on JVM, or JVM options, these treatments can actually be slower than Math ones. In particular, they can be slower if not optimized by the JIT, which you can see with -Xint JVM option. Another cause of slowness can be cache-misses on look-up tables. Also, look-up tables initialization typically takes multiple hundreds of milliseconds (and is about twice slower in J6 than in J5, and in J7 than in J6, possibly due to intrinsifications preventing optimizations such as use of hardware sqrt, and Math delegating to StrictMath with JIT optimizations not yet up during class load). As a result, you might want to make these treatments not use tables, and delegate to corresponding Math methods, when they are available in the lowest supported Java version, by using the appropriate properties (see below).

• About StrictFastMath: Unlike StrictMath, StrictFastMath is not supposed to behave identically across versions, and even for a same version it might behave differently depending on its configuration (properties). It is just supposed to behave identically for a same version and configuration, which can still be useful, for example for racily computed cached values in immutable instances. Other than strictness and usually lower performances due to strictfp overhead, the only differences with FastMath are its properties, and copySign(float,float) and copySign(double,double) semantics.

Properties for FastMath class treatments

• jafama.usejdk (boolean, default is false): If true, for redefined methods, as well as their "Fast" or "Quick" terminated counterparts, instead of using redefined computations, delegating to Math, when available in required Java version.

• jafama.fastlog (boolean, default is false): If true, using redefined computations for log(double) and log10(double), else they delegate to Math.log(double) and Math.log10(double). False by default because Math.log(double) and Math.log10(double) seem usually fast (redefined log(double) might be even faster, but is less accurate).

• jafama.fastsqrt (boolean, default is false): If true, using redefined computation for sqrt(double), else it delegates to Math.sqrt(double). False by default because Math.sqrt(double) seems usually fast.

Properties for StrictFastMath class treatments

• jafama.strict.usejdk (boolean, default is false): If true, for redefined methods, as well as their "Fast" or "Quick" terminated counterparts, instead of using redefined computations, delegating to StrictMath, when available in required Java version.

• jafama.strict.fastlog (boolean, default is true): If true, using redefined computations for log(double) and log10(double), else they delegate to StrictMath.log(double) and StrictMath.log10(double). True by default because StrictMath.log(double) and StrictMath.log10(double) can be quite slow.

• jafama.strict.fastsqrt (boolean, default is false): If true, using redefined computation for sqrt(double), else it delegates to StrictMath.sqrt(double). False by default because StrictMath.sqrt(double) seems usually fast.

Donation