Top Description Inners Fields Constructors Methods
org.apache.commons.math3.util

public Class FastMath

extends Object
Class Inheritance
Imports
java.io.PrintStream, org.apache.commons.math3.exception.MathArithmeticException, org.apache.commons.math3.exception.util.LocalizedFormats

Faster, more accurate, portable alternative to Math and StrictMath for large scale computation.

FastMath is a drop-in replacement for both Math and StrictMath. This means that for any method in Math (say Math.sin(x) or Math.cbrt(y)), user can directly change the class and use the methods as is (using FastMath.sin(x) or FastMath.cbrt(y) in the previous example).

FastMath speed is achieved by relying heavily on optimizing compilers to native code present in many JVMs today and use of large tables. The larger tables are lazily initialised on first use, so that the setup time does not penalise methods that don't need them.

Note that FastMath is extensively used inside Apache Commons Math, so by calling some algorithms, the overhead when the the tables need to be intialised will occur regardless of the end-user calling FastMath methods directly or not. Performance figures for a specific JVM and hardware can be evaluated by running the FastMathTestPerformance tests in the test directory of the source distribution.

FastMath accuracy should be mostly independent of the JVM as it relies only on IEEE-754 basic operations and on embedded tables. Almost all operations are accurate to about 0.5 ulp throughout the domain range. This statement, of course is only a rough global observed behavior, it is not a guarantee for every double numbers input (see William Kahan's Table Maker's Dilemma).

FastMath additionally implements the following methods not found in Math/StrictMath:

The following methods are found in Math/StrictMath since 1.6 only, they are provided by FastMath even in 1.5 Java virtual machines

Since
2.2

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
FastMath.CodyWaite

Enclose the Cody/Waite reduction (used in "sin", "cos" and "tan").

private static class
FastMath.ExpFracTable

Enclose large data table in nested static class so it's only loaded on first access.

private static class
FastMath.ExpIntTable

Enclose large data table in nested static class so it's only loaded on first access.

private static class
FastMath.lnMant

Enclose large data table in nested static class so it's only loaded on first access.

private static class
FastMath.Split

Class operator on double numbers split into one 26 bits number and one 27 bits number.

Field Summary

Modifier and TypeField and Description
private static final double[]
CBRTTWO

Table of 2^((n+2)/3)

private static final double[]
COSINE_TABLE_A

Cosine table (high bits).

private static final double[]
COSINE_TABLE_B

Cosine table (low bits).

public static final double
E

Napier's constant e, base of the natural logarithm.

private static final double[]
EIGHTHS

Eighths.

pack-priv static final int
EXP_FRAC_TABLE_LEN

Exponential fractions table length.

pack-priv static final int
EXP_INT_TABLE_LEN

Length of the array of integer exponentials.

pack-priv static final int
EXP_INT_TABLE_MAX_INDEX

Index of exp(0) in the array of integer exponentials.

private static final double
F_11_12

Constant: .

private static final double
F_13_14

Constant: .

private static final double
F_15_16

Constant: .

private static final double
F_1_11

Constant: .

private static final double
F_1_13

Constant: .

private static final double
F_1_15

Constant: .

private static final double
F_1_17

Constant: .

private static final double
F_1_2

Constant: .

private static final double
F_1_3

Constant: .

private static final double
F_1_4

Constant: .

private static final double
F_1_5

Constant: .

private static final double
F_1_7

Constant: .

private static final double
F_1_9

Constant: .

private static final double
F_3_4

Constant: .

private static final double
F_5_6

Constant: .

private static final double
F_7_8

Constant: .

private static final double
F_9_10

Constant: .

private static final long
HEX_40000000

0x40000000 - used to split a double into two parts, both with the low order bits cleared.

private static final long
IMPLICIT_HIGH_BIT

Mask used to add implicit high order bit for normalized double.

private static final double
LN_2_A

log(2) (high bits).

private static final double
LN_2_B

log(2) (low bits).

private static final double[][]
LN_HI_PREC_COEF

Coefficients for log in the range of 1.0 < x < 1.0 + 2^-10.

pack-priv static final int
LN_MANT_LEN

Logarithm table length.

private static final double[][]
LN_QUICK_COEF

Coefficients for log, when input 0.99 < x < 1.01.

private static final double
LOG_MAX_VALUE

StrictMath.log(Double.MAX_VALUE):

private static final long
MASK_30BITS

Mask used to clear low order 30 bits

private static final long
MASK_DOUBLE_EXPONENT

Mask used to extract exponent from double bits.

private static final long
MASK_DOUBLE_MANTISSA

Mask used to extract mantissa from double bits.

private static final int
MASK_NON_SIGN_INT

Mask used to clear the non-sign part of an int.

private static final long
MASK_NON_SIGN_LONG

Mask used to clear the non-sign part of a long.

public static final double
PI

Archimede's constant PI, ratio of circle circumference to diameter.

private static final long[]
PI_O_4_BITS

Bits of pi/4, need for reducePayneHanek().

private static final long[]
RECIP_2PI

Bits of 1/(2*pi), need for reducePayneHanek().

private static final boolean
RECOMPUTE_TABLES_AT_RUNTIME

Indicator for tables initialization.

private static final double[]
SINE_TABLE_A

Sine table (high bits).

private static final double[]
SINE_TABLE_B

Sine table (low bits).

private static final int
SINE_TABLE_LEN

Sine, Cosine, Tangent tables are for 0, 1/8, 2/8, ...

private static final double[]
TANGENT_TABLE_A

Tangent table, used by atan() (high bits).

private static final double[]
TANGENT_TABLE_B

Tangent table, used by atan() (low bits).

private static final double
TWO_POWER_52

2^52 - double numbers this large must be integral (no fraction) or NaN or Infinite

Constructor Summary

AccessConstructor and Description
private
FastMath()

Private Constructor

Method Summary

Modifier and TypeMethod and Description
public static int

Returns:

abs(x)
abs
(final int
number from which absolute value is requested
x
)

Absolute value.

public static long

Returns:

abs(x)
abs
(final long
number from which absolute value is requested
x
)

Absolute value.

public static float

Returns:

abs(x)
abs
(final float
number from which absolute value is requested
x
)

Absolute value.

public static double

Returns:

abs(x)
abs
(double
number from which absolute value is requested
x
)

Absolute value.

public static double

Returns:

arc cosine of x
acos
(double
number on which evaluation is done
x
)

Compute the arc cosine of a number.

public static double

Returns:

inverse hyperbolic cosine of a
acosh
(final double
number on which evaluation is done
a
)

Compute the inverse hyperbolic cosine of a number.

public static int

Returns:

a+b if no overflows occur
addExact
(final int
first number to add
a
,
final int
second number to add
b
)

Add two numbers, detecting overflows.

public static long

Returns:

a+b if no overflows occur
addExact
(final long
first number to add
a
,
final long
second number to add
b
)

Add two numbers, detecting overflows.

public static double

Returns:

arc sine of x
asin
(double
number on which evaluation is done
x
)

Compute the arc sine of a number.

public static double

Returns:

inverse hyperbolic sine of a
asinh
(double
number on which evaluation is done
a
)

Compute the inverse hyperbolic sine of a number.

public static double

Returns:

atan(x)
atan
(double
a number
x
)

Arctangent function

private static double

Returns:

atan(xa + xb) (or angle shifted by PI if leftPlane is true)
atan
(double
number from which arctangent is requested
xa
,
double
extra bits for x (may be 0.0)
xb
,
boolean
if true, result angle must be put in the left half plane
leftPlane
)

Internal helper function to compute arctangent.

public static double

Returns:

phase angle of point (x,y) between -PI and PI
atan2
(double
ordinate
y
,
double
abscissa
x
)

Two arguments arctangent function

public static double

Returns:

inverse hyperbolic tangent of a
atanh
(double
number on which evaluation is done
a
)

Compute the inverse hyperbolic tangent of a number.

public static double

Returns:

cubic root of x
cbrt
(double
number on which evaluation is done
x
)

Compute the cubic root of a number.

public static double

Returns:

a double number c such that c is an integer c - 1.0 < x <= c
ceil
(double
number from which ceil is requested
x
)

Get the smallest whole number larger than x.

public static double

Returns:

the magnitude with the same sign as the sign argument
copySign
(double
the value to return
magnitude
,
double
the sign for the returned value
sign
)

Returns the first argument with the sign of the second argument.

public static float

Returns:

the magnitude with the same sign as the sign argument
copySign
(float
the value to return
magnitude
,
float
the sign for the returned value
sign
)

Returns the first argument with the sign of the second argument.

public static double

Returns:

cos(x)
cos
(double
Argument.
x
)

Cosine function.

public static double

Returns:

hyperbolic cosine of x
cosh
(double
number on which evaluation is done
x
)

Compute the hyperbolic cosine of a number.

private static double

Returns:

cos(xa + xb)
cosQ
(double
number from which cosine is requested
xa
,
double
extra bits for x (may be 0.0)
xb
)

Compute cosine in the first quadrant by subtracting input from PI/2 and then calling sinQ.

public static int

Returns:

n-1 if no overflows occur
decrementExact
(final int
number to decrement
n
)

Decrement a number, detecting overflows.

public static long

Returns:

n-1 if no overflows occur
decrementExact
(final long
number to decrement
n
)

Decrement a number, detecting overflows.

private static double

Returns:

the high order part of the mantissa
doubleHighPart
(double
the value to split
d
)

Get the high order bits from the mantissa.

public static double

Returns:

double ex
exp
(double
a double
x
)

Exponential function.

private static double

Returns:

exp(x)
exp
(double
original argument of the exponential function
x
,
double
extra bits of precision on input (To Be Confirmed)
extra
,
double[]
extra bits of precision on output (To Be Confirmed)
hiPrec
)

Internal helper method for exponential function.

public static double

Returns:

exp(x) - 1
expm1
(double
number to compute shifted exponential
x
)

Compute exp(x) - 1

private static double

Returns:

exp(x) - 1
expm1
(double
number to compute shifted exponential
x
,
double[]
receive high precision result for -1.0 < x < 1.0
hiPrecOut
)

Internal helper method for expm1

public static double

Returns:

a double number f such that f is an integer f <= x < f + 1.0
floor
(double
number from which floor is requested
x
)

Get the largest whole number smaller than x.

public static int

Returns:

q such that a = q b + r with 0 <= r < b if b > 0 and b < r <= 0 if b < 0
floorDiv
(final int
dividend
a
,
final int
divisor
b
)

Finds q such that a = q b + r with 0 <= r < b if b > 0 and b < r <= 0 if b < 0.

public static long

Returns:

q such that a = q b + r with 0 <= r < b if b > 0 and b < r <= 0 if b < 0
floorDiv
(final long
dividend
a
,
final long
divisor
b
)

Finds q such that a = q b + r with 0 <= r < b if b > 0 and b < r <= 0 if b < 0.

public static int

Returns:

r such that a = q b + r with 0 <= r < b if b > 0 and b < r <= 0 if b < 0
floorMod
(final int
dividend
a
,
final int
divisor
b
)

Finds r such that a = q b + r with 0 <= r < b if b > 0 and b < r <= 0 if b < 0.

public static long

Returns:

r such that a = q b + r with 0 <= r < b if b > 0 and b < r <= 0 if b < 0
floorMod
(final long
dividend
a
,
final long
divisor
b
)

Finds r such that a = q b + r with 0 <= r < b if b > 0 and b < r <= 0 if b < 0.

public static int

Returns:

exponent for d in IEEE754 representation, without bias
getExponent
(final double
number from which exponent is requested
d
)

Return the exponent of a double number, removing the bias.

public static int

Returns:

exponent for d in IEEE754 representation, without bias
getExponent
(final float
number from which exponent is requested
f
)

Return the exponent of a float number, removing the bias.

public static double

Returns:

sqrt(x2 +y2)
hypot
(final double
a value
x
,
final double
a value
y
)

Returns the hypotenuse of a triangle with sides x and y - sqrt(x2 +y2) avoiding intermediate overflow or underflow.

public static double

Returns:

the remainder, rounded
IEEEremainder
(double
the number to be divided
dividend
,
double
the number by which to divide
divisor
)

Computes the remainder as prescribed by the IEEE 754 standard.

public static int

Returns:

n+1 if no overflows occur
incrementExact
(final int
number to increment
n
)

Increment a number, detecting overflows.

public static long

Returns:

n+1 if no overflows occur
incrementExact
(final long
number to increment
n
)

Increment a number, detecting overflows.

public static double

Returns:

log(x)
log
(final double
a double
x
)

Natural logarithm.

private static double

Returns:

log(x)
log
(final double
original argument of the natural logarithm function
x
,
final double[]
extra bits of precision on output (To Be Confirmed)
hiPrec
)

Internal helper method for natural logarithm function.

public static double

Returns:

the value of the logarithm, i.e. the number y such that basey = x.
log
(double
Base of the logarithm, must be greater than 0.
base
,
double
Argument, must be greater than 0.
x
)

Computes the logarithm in a given base.

public static double

Returns:

log10(x)
log10
(final double
a number
x
)

Compute the base 10 logarithm.

public static double

Returns:

log(1 + x).
log1p
(final double
Number.
x
)

Computes log(1 + x).

public static void
main(String[]
unused
a
)

Print out contents of arrays, and check the length.

public static int

Returns:

b if a is lesser or equal to b, a otherwise
max
(final int
first value
a
,
final int
second value
b
)

Compute the maximum of two values

public static long

Returns:

b if a is lesser or equal to b, a otherwise
max
(final long
first value
a
,
final long
second value
b
)

Compute the maximum of two values

public static float

Returns:

b if a is lesser or equal to b, a otherwise
max
(final float
first value
a
,
final float
second value
b
)

Compute the maximum of two values

public static double

Returns:

b if a is lesser or equal to b, a otherwise
max
(final double
first value
a
,
final double
second value
b
)

Compute the maximum of two values

public static int

Returns:

a if a is lesser or equal to b, b otherwise
min
(final int
first value
a
,
final int
second value
b
)

Compute the minimum of two values

public static long

Returns:

a if a is lesser or equal to b, b otherwise
min
(final long
first value
a
,
final long
second value
b
)

Compute the minimum of two values

public static float

Returns:

a if a is lesser or equal to b, b otherwise
min
(final float
first value
a
,
final float
second value
b
)

Compute the minimum of two values

public static double

Returns:

a if a is lesser or equal to b, b otherwise
min
(final double
first value
a
,
final double
second value
b
)

Compute the minimum of two values

public static int

Returns:

a*b if no overflows occur
multiplyExact
(final int
first number to multiply
a
,
final int
second number to multiply
b
)

Multiply two numbers, detecting overflows.

public static long

Returns:

a*b if no overflows occur
multiplyExact
(final long
first number to multiply
a
,
final long
second number to multiply
b
)

Multiply two numbers, detecting overflows.

public static double

Returns:

the next machine representable number in the specified direction
nextAfter
(double
base number
d
,
double
(the only important thing is whether direction is greater or smaller than d)
direction
)

Get the next machine representable number after a number, moving in the direction of another number.

public static float

Returns:

the next machine representable number in the specified direction
nextAfter
(final float
base number
f
,
final double
(the only important thing is whether direction is greater or smaller than f)
direction
)

Get the next machine representable number after a number, moving in the direction of another number.

public static double

Returns:

neighbor of a towards negative infinity
nextDown
(final double
number to which neighbor should be computed
a
)

Compute next number towards negative infinity.

public static float

Returns:

neighbor of a towards negative infinity
nextDown
(final float
number to which neighbor should be computed
a
)

Compute next number towards negative infinity.

public static double

Returns:

neighbor of a towards positive infinity
nextUp
(final double
number to which neighbor should be computed
a
)

Compute next number towards positive infinity.

public static float

Returns:

neighbor of a towards positive infinity
nextUp
(final float
number to which neighbor should be computed
a
)

Compute next number towards positive infinity.

private static double

Returns:

cos(x) - 1
polyCosine
(double
a number smaller than 1/16
x
)

Computes cos(x) - 1, where |x| < 1/16.

private static double

Returns:

sin(x) - x
polySine
(final double
a number smaller than 1/16
x
)

Computes sin(x) - x, where |x| < 1/16.

public static double

Returns:

double
pow
(final double
a double
x
,
final double
a double
y
)

Power function.

public static double

Returns:

de
pow
(double
Number to raise.
d
,
int
Exponent.
e
)

Raise a double to an int power.

public static double

Returns:

de
pow
(double
Number to raise.
d
,
long
Exponent.
e
)

Raise a double to a long power.

public static double

Returns:

a random number between 0.0 and 1.0
random
()

Returns a pseudo-random number between 0.0 and 1.0.

private static void
reducePayneHanek(double
number to reduce
x
,
double[]
placeholder where to put the result
result
)

Reduce the input argument using the Payne and Hanek method.

public static double

Returns:

a double number r such that r is an integer r - 0.5 <= x <= r + 0.5
rint
(double
number from which nearest whole number is requested
x
)

Get the whole number that is the nearest to x, or the even one if x is exactly half way between two integers.

public static long

Returns:

closest long to x
round
(double
number from which closest long is requested
x
)

Get the closest long to x.

public static int

Returns:

closest int to x
round
(final float
number from which closest int is requested
x
)

Get the closest int to x.

public static double

Returns:

d × 2n
scalb
(final double
number to multiply
d
,
final int
power of 2
n
)

Multiply a double number by a power of 2.

public static float

Returns:

f × 2n
scalb
(final float
number to multiply
f
,
final int
power of 2
n
)

Multiply a float number by a power of 2.

public static double

Returns:

-1.0, -0.0, +0.0, +1.0 or NaN depending on sign of a
signum
(final double
number on which evaluation is done
a
)

Compute the signum of a number.

public static float

Returns:

-1.0, -0.0, +0.0, +1.0 or NaN depending on sign of a
signum
(final float
number on which evaluation is done
a
)

Compute the signum of a number.

public static double

Returns:

sin(x)
sin
(double
Argument.
x
)

Sine function.

public static double

Returns:

hyperbolic sine of x
sinh
(double
number on which evaluation is done
x
)

Compute the hyperbolic sine of a number.

private static double

Returns:

sin(xa + xb)
sinQ
(double
number from which sine is requested
xa
,
double
extra bits for x (may be 0.0)
xb
)

Compute sine over the first quadrant (0 < x < pi/2).

public static double

Returns:

square root of a
sqrt
(final double
number on which evaluation is done
a
)

Compute the square root of a number.

public static int

Returns:

a-b if no overflows occur
subtractExact
(final int
first number
a
,
final int
second number to subtract from a
b
)

Subtract two numbers, detecting overflows.

public static long

Returns:

a-b if no overflows occur
subtractExact
(final long
first number
a
,
final long
second number to subtract from a
b
)

Subtract two numbers, detecting overflows.

public static double

Returns:

tan(x)
tan
(double
Argument.
x
)

Tangent function.

public static double

Returns:

hyperbolic tangent of x
tanh
(double
number on which evaluation is done
x
)

Compute the hyperbolic tangent of a number.

private static double

Returns:

tan(xa+xb) (or cotangent, depending on cotanFlag)
tanQ
(double
number from which sine is requested
xa
,
double
extra bits for x (may be 0.0)
xb
,
boolean
if true, compute the cotangent instead of the tangent
cotanFlag
)

Compute tangent (or cotangent) over the first quadrant.

public static double

Returns:

x converted into degrees
toDegrees
(double
angle in radians
x
)

Convert radians to degrees, with error of less than 0.5 ULP

public static int

Returns:

integer with same valie as n if no overflows occur
toIntExact
(final long
number to convert to int
n
)

Convert a long to interger, detecting overflows

public static double

Returns:

x converted into radians
toRadians
(double
angle in degrees
x
)

Convert degrees to radians, with error of less than 0.5 ULP

public static double

Returns:

ulp(x)
ulp
(double
number from which ulp is requested
x
)

Compute least significant bit (Unit in Last Position) for a number.

public static float

Returns:

ulp(x)
ulp
(float
number from which ulp is requested
x
)

Compute least significant bit (Unit in Last Position) for a number.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait