org.apache.commons.math3.util
Class FastMath

java.lang.Object
  extended by org.apache.commons.math3.util.FastMath

public class FastMath
extends Object

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

This version of FastMath never returns Double.NaN values. If result cannot be returned because undefined, an ArithmeticException is returned.

Since:
2.2
Version:
$Id: FastMath.java 17623 2017-05-19 07:45:31Z bignon $

Field Summary
static double E
          Napier's constant e, base of the natural logarithm.
static double PI
          Archimede's constant PI, ratio of circle circumference to diameter.
 
Method Summary
static double abs(double x)
          Absolute value.
static float abs(float x)
          Absolute value.
static int abs(int x)
          Absolute value.
static long abs(long x)
          Absolute value.
static double acos(double x)
          Compute the arc cosine of a number.
static double acosh(double a)
          Compute the inverse hyperbolic cosine of a number.
static double asin(double x)
          Compute the arc sine of a number.
static double asinh(double a)
          Compute the inverse hyperbolic sine of a number.
static double atan(double x)
          Arctangent function
static double atan2(double y, double x)
          Two arguments arctangent function
static double atanh(double a)
          Compute the inverse hyperbolic tangent of a number.
static double cbrt(double x)
          Compute the cubic root of a number.
static double ceil(double x)
          Get the smallest whole number larger than x.
static double copySign(double magnitude, double sign)
          Returns the first argument with the sign of the second argument.
static float copySign(float magnitude, float sign)
          Returns the first argument with the sign of the second argument.
static double cos(double x)
          Cosine function.
static double cosh(double x)
          Compute the hyperbolic cosine of a number.
static double divide(double x, double y)
          Computes x / y
static double exp(double x)
          Exponential function.
static double expm1(double x)
          Compute exp(x) - 1
static double floor(double x)
          Get the largest whole number smaller than x.
static int getExponent(double d)
          Return the exponent of a double number, removing the bias.
static int getExponent(float f)
          Return the exponent of a float number, removing the bias.
static double hypot(double x, double y)
          Returns the hypotenuse of a triangle with sides x and y - sqrt(x2 +y2)
avoiding intermediate overflow or underflow.
static double IEEEremainder(double dividend, double divisor)
          Computes the remainder as prescribed by the IEEE 754 standard.
static double log(double x)
          Natural logarithm.
static double log(double base, double x)
          Computes the logarithm in a given base.
static double log10(double x)
          Compute the base 10 logarithm.
static double log1p(double x)
          Computes log(1 + x).
static void main(String[] a)
          Print out contents of arrays, and check the length.
static double max(double a, double b)
          Compute the maximum of two values
static float max(float a, float b)
          Compute the maximum of two values
static int max(int a, int b)
          Compute the maximum of two values
static long max(long a, long b)
          Compute the maximum of two values
static double min(double a, double b)
          Compute the minimum of two values
static float min(float a, float b)
          Compute the minimum of two values
static int min(int a, int b)
          Compute the minimum of two values
static long min(long a, long b)
          Compute the minimum of two values
static double nextAfter(double d, double direction)
          Get the next machine representable number after a number, moving in the direction of another number.
static float nextAfter(float f, double direction)
          Get the next machine representable number after a number, moving in the direction of another number.
static double nextUp(double a)
          Compute next number towards positive infinity.
static float nextUp(float a)
          Compute next number towards positive infinity.
static double pow(double x, double y)
          Power function.
static double pow(double d, int e)
          Raise a double to an int power.
static double random()
          Returns a pseudo-random number between 0.0 and 1.0.
static double rint(double x)
          Get the whole number that is the nearest to x, or the even one if x is exactly half way between two integers.
static long round(double x)
          Get the closest long to x.
static int round(float x)
          Get the closest int to x.
static double scalb(double d, int n)
          Multiply a double number by a power of 2.
static float scalb(float f, int n)
          Multiply a float number by a power of 2.
static double signum(double a)
          Compute the signum of a number.
static float signum(float a)
          Compute the signum of a number.
static double sin(double x)
          Sine function.
static double sinh(double x)
          Compute the hyperbolic sine of a number.
static double sqrt(double a)
          Compute the square root of a number.
static double tan(double x)
          Tangent function.
static double tanh(double x)
          Compute the hyperbolic tangent of a number.
static double toDegrees(double x)
          Convert radians to degrees, with error of less than 0.5 ULP
static double toRadians(double x)
          Convert degrees to radians, with error of less than 0.5 ULP
static double ulp(double x)
          Compute least significant bit (Unit in Last Position) for a number.
static float ulp(float x)
          Compute least significant bit (Unit in Last Position) for a number.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

PI

public static final double PI
Archimede's constant PI, ratio of circle circumference to diameter.

See Also:
Constant Field Values

E

public static final double E
Napier's constant e, base of the natural logarithm.

See Also:
Constant Field Values
Method Detail

sqrt

public static double sqrt(double a)
                   throws ArithmeticException
Compute the square root of a number.

Note: this implementation currently delegates to Math.sqrt(double)

Parameters:
a - number on which evaluation is done
Returns:
square root of a
Throws:
ArithmeticException - thrown if a < 0 or a is NaN

cosh

public static double cosh(double x)
                   throws ArithmeticException
Compute the hyperbolic cosine of a number.

Parameters:
x - number on which evaluation is done
Returns:
hyperbolic cosine of x
Throws:
ArithmeticException - thrown if x is NaN

sinh

public static double sinh(double x)
                   throws ArithmeticException
Compute the hyperbolic sine of a number.

Parameters:
x - number on which evaluation is done
Returns:
hyperbolic sine of x
Throws:
ArithmeticException - thrown if x is NaN

tanh

public static double tanh(double x)
                   throws ArithmeticException
Compute the hyperbolic tangent of a number.

Parameters:
x - number on which evaluation is done
Returns:
hyperbolic tangent of x
Throws:
ArithmeticException - thrown if a is NaN

acosh

public static double acosh(double a)
                    throws ArithmeticException
Compute the inverse hyperbolic cosine of a number.

Parameters:
a - number on which evaluation is done
Returns:
inverse hyperbolic cosine of a
Throws:
ArithmeticException - thrown if a < 1 or a is NaN

asinh

public static double asinh(double a)
                    throws ArithmeticException
Compute the inverse hyperbolic sine of a number.

Parameters:
a - number on which evaluation is done
Returns:
inverse hyperbolic sine of a
Throws:
ArithmeticException - thrown if a is NaN

atanh

public static double atanh(double a)
                    throws ArithmeticException
Compute the inverse hyperbolic tangent of a number.

Parameters:
a - number on which evaluation is done
Returns:
inverse hyperbolic tangent of a
Throws:
ArithmeticException - thrown if a > 1 or a < -1 or a is NaN

signum

public static double signum(double a)
                     throws ArithmeticException
Compute the signum of a number. The signum is -1 for negative numbers, +1 for positive numbers and 0 otherwise

Parameters:
a - number on which evaluation is done
Returns:
-1.0, -0.0, +0.0, +1.0 or NaN depending on sign of a
Throws:
ArithmeticException - thrown if a is NaN

signum

public static float signum(float a)
                    throws ArithmeticException
Compute the signum of a number. The signum is -1 for negative numbers, +1 for positive numbers and 0 otherwise

Parameters:
a - number on which evaluation is done
Returns:
-1.0, -0.0, +0.0, +1.0 or NaN depending on sign of a
Throws:
ArithmeticException - thrown if a is NaN

nextUp

public static double nextUp(double a)
                     throws ArithmeticException
Compute next number towards positive infinity.

Parameters:
a - number to which neighbor should be computed
Returns:
neighbor of a towards positive infinity
Throws:
ArithmeticException - thrown if a is NaN

nextUp

public static float nextUp(float a)
                    throws ArithmeticException
Compute next number towards positive infinity.

Parameters:
a - number to which neighbor should be computed
Returns:
neighbor of a towards positive infinity
Throws:
ArithmeticException - thrown if a is NaN

random

public static double random()
Returns a pseudo-random number between 0.0 and 1.0.

Note: this implementation currently delegates to Math.random()

Returns:
a random number between 0.0 and 1.0

exp

public static double exp(double x)
                  throws ArithmeticException
Exponential function. Computes exp(x), function result is nearly rounded. It will be correctly rounded to the theoretical value for 99.9% of input values, otherwise it will have a 1 UPL error. Method: Lookup intVal = exp(int(x)) Lookup fracVal = exp(int(x-int(x) / 1024.0) * 1024.0 ); Compute z as the exponential of the remaining bits by a polynomial minus one exp(x) = intVal * fracVal * (1 + z) Accuracy: Calculation is done with 63 bits of precision, so result should be correctly rounded for 99.9% of input values, with less than 1 ULP error otherwise.

Parameters:
x - a double
Returns:
double ex
Throws:
ArithmeticException - thrown if x is NaN

expm1

public static double expm1(double x)
                    throws ArithmeticException
Compute exp(x) - 1

Parameters:
x - number to compute shifted exponential
Returns:
exp(x) - 1
Throws:
ArithmeticException - thrown if x is NaN

log

public static double log(double x)
                  throws ArithmeticException
Natural logarithm.

Parameters:
x - a double
Returns:
log(x)
Throws:
ArithmeticException - thrown if x < 0 or x is NaN

log1p

public static double log1p(double x)
                    throws ArithmeticException
Computes log(1 + x).

Parameters:
x - Number.
Returns:
log(1 + x).
Throws:
ArithmeticException - thrown if x < 0 or x is NaN

log10

public static double log10(double x)
                    throws ArithmeticException
Compute the base 10 logarithm.

Parameters:
x - a number
Returns:
log10(x)
Throws:
ArithmeticException - thrown if x < 0 or x is NaN

log

public static double log(double base,
                         double x)
                  throws ArithmeticException
Computes the logarithm in a given base. Returns NaN if either argument is negative. If base is 0 and x is positive, 0 is returned. If base is positive and x is 0, Double.NEGATIVE_INFINITY is returned. If both arguments are 0, the result is NaN.

Parameters:
base - Base of the logarithm, must be greater than 0.
x - Argument, must be greater than 0.
Returns:
the value of the logarithm, i.e. the number y such that basey = x.
Throws:
ArithmeticException - thrown if x < 0 or (base or x) is NaN or base and x = 0
Since:
1.2 (previously in MathUtils, moved as of version 3.0)

pow

public static double pow(double x,
                         double y)
                  throws ArithmeticException
Power function. Compute x^y.

Parameters:
x - a double
y - a double
Returns:
double
Throws:
ArithmeticException - thrown if y < 0 and y not an integer or x or y is NaN or x = -1

pow

public static double pow(double d,
                         int e)
                  throws ArithmeticException
Raise a double to an int power.

Parameters:
d - Number to raise.
e - Exponent.
Returns:
de
Throws:
ArithmeticException - thrown if d is NaN
Since:
3.1

sin

public static double sin(double x)
                  throws ArithmeticException
Sine function.

Parameters:
x - Argument.
Returns:
sin(x)
Throws:
ArithmeticException - thrown if x is NaN or Infinity

cos

public static double cos(double x)
Cosine function.

Parameters:
x - Argument.
Returns:
cos(x)
Throws:
ArithmeticException - thrown if x is NaN or Infinity

tan

public static double tan(double x)
                  throws ArithmeticException
Tangent function.

Parameters:
x - Argument.
Returns:
tan(x)
Throws:
ArithmeticException - thrown if x is NaN or Infinity

atan

public static double atan(double x)
                   throws ArithmeticException
Arctangent function

Parameters:
x - a number
Returns:
atan(x)
Throws:
ArithmeticException - thrown if x is NaN

atan2

public static double atan2(double y,
                           double x)
                    throws ArithmeticException
Two arguments arctangent function

Parameters:
y - ordinate
x - abscissa
Returns:
phase angle of point (x,y) between -PI and PI
Throws:
ArithmeticException - thrown if x or y is NaN

asin

public static double asin(double x)
                   throws ArithmeticException
Compute the arc sine of a number.

Parameters:
x - number on which evaluation is done
Returns:
arc sine of x
Throws:
ArithmeticException - thrown if x < -1 or x > 1 or x is NaN

acos

public static double acos(double x)
                   throws ArithmeticException
Compute the arc cosine of a number.

Parameters:
x - number on which evaluation is done
Returns:
arc cosine of x
Throws:
ArithmeticException - thrown if x < -1 or x > 1 or x is NaN

cbrt

public static double cbrt(double x)
                   throws ArithmeticException
Compute the cubic root of a number.

Parameters:
x - number on which evaluation is done
Returns:
cubic root of x
Throws:
ArithmeticException - thrown if x is NaN

toRadians

public static double toRadians(double x)
                        throws ArithmeticException
Convert degrees to radians, with error of less than 0.5 ULP

Parameters:
x - angle in degrees
Returns:
x converted into radians
Throws:
ArithmeticException - thrown if x is NaN

toDegrees

public static double toDegrees(double x)
                        throws ArithmeticException
Convert radians to degrees, with error of less than 0.5 ULP

Parameters:
x - angle in radians
Returns:
x converted into degrees
Throws:
ArithmeticException - thrown if x is NaN

abs

public static int abs(int x)
Absolute value.

Parameters:
x - number from which absolute value is requested
Returns:
abs(x)

abs

public static long abs(long x)
Absolute value.

Parameters:
x - number from which absolute value is requested
Returns:
abs(x)

abs

public static float abs(float x)
                 throws ArithmeticException
Absolute value.

Parameters:
x - number from which absolute value is requested
Returns:
abs(x)
Throws:
ArithmeticException - thrown if x is NaN

abs

public static double abs(double x)
                  throws ArithmeticException
Absolute value.

Parameters:
x - number from which absolute value is requested
Returns:
abs(x)
Throws:
ArithmeticException - thrown if x is NaN

ulp

public static double ulp(double x)
                  throws ArithmeticException
Compute least significant bit (Unit in Last Position) for a number.

Parameters:
x - number from which ulp is requested
Returns:
ulp(x)
Throws:
ArithmeticException - thrown if x is NaN

ulp

public static float ulp(float x)
                 throws ArithmeticException
Compute least significant bit (Unit in Last Position) for a number.

Parameters:
x - number from which ulp is requested
Returns:
ulp(x)
Throws:
ArithmeticException - thrown if x is NaN

scalb

public static double scalb(double d,
                           int n)
                    throws ArithmeticException
Multiply a double number by a power of 2.

Parameters:
d - number to multiply
n - power of 2
Returns:
d × 2n
Throws:
ArithmeticException - thrown if d is NaN

scalb

public static float scalb(float f,
                          int n)
                   throws ArithmeticException
Multiply a float number by a power of 2.

Parameters:
f - number to multiply
n - power of 2
Returns:
f × 2n
Throws:
ArithmeticException - thrown if f is NaN

nextAfter

public static double nextAfter(double d,
                               double direction)
                        throws ArithmeticException
Get the next machine representable number after a number, moving in the direction of another number.

The ordering is as follows (increasing):


nextAfter

public static float nextAfter(float f,
                              double direction)
                       throws ArithmeticException
Get the next machine representable number after a number, moving in the direction of another number.

The ordering is as follows (increasing):


floor

public static double floor(double x)
                    throws ArithmeticException
Get the largest whole number smaller than x.

Parameters:
x - number from which floor is requested
Returns:
a double number f such that f is an integer f <= x < f + 1.0
Throws:
ArithmeticException - thrown if x is NaN

ceil

public static double ceil(double x)
                   throws ArithmeticException
Get the smallest whole number larger than x.

Parameters:
x - number from which ceil is requested
Returns:
a double number c such that c is an integer c - 1.0 < x <= c
Throws:
ArithmeticException - thrown if x is NaN

rint

public static double rint(double x)
                   throws ArithmeticException
Get the whole number that is the nearest to x, or the even one if x is exactly half way between two integers.

Parameters:
x - number from which nearest whole number is requested
Returns:
a double number r such that r is an integer r - 0.5 <= x <= r + 0.5
Throws:
ArithmeticException - thrown if x is NaN

round

public static long round(double x)
                  throws ArithmeticException
Get the closest long to x.

Parameters:
x - number from which closest long is requested
Returns:
closest long to x
Throws:
ArithmeticException - thrown if x is NaN

round

public static int round(float x)
                 throws ArithmeticException
Get the closest int to x.

Parameters:
x - number from which closest int is requested
Returns:
closest int to x
Throws:
ArithmeticException - thrown if x is NaN

min

public static int min(int a,
                      int b)
Compute the minimum of two values

Parameters:
a - first value
b - second value
Returns:
a if a is lesser or equal to b, b otherwise

min

public static long min(long a,
                       long b)
Compute the minimum of two values

Parameters:
a - first value
b - second value
Returns:
a if a is lesser or equal to b, b otherwise

min

public static float min(float a,
                        float b)
                 throws ArithmeticException
Compute the minimum of two values

Parameters:
a - first value
b - second value
Returns:
a if a is lesser or equal to b, b otherwise
Throws:
ArithmeticException - thrown if a or b is NaN

min

public static double min(double a,
                         double b)
                  throws ArithmeticException
Compute the minimum of two values

Parameters:
a - first value
b - second value
Returns:
a if a is lesser or equal to b, b otherwise
Throws:
ArithmeticException - thrown if a or b is NaN

max

public static int max(int a,
                      int b)
Compute the maximum of two values

Parameters:
a - first value
b - second value
Returns:
b if a is lesser or equal to b, a otherwise

max

public static long max(long a,
                       long b)
Compute the maximum of two values

Parameters:
a - first value
b - second value
Returns:
b if a is lesser or equal to b, a otherwise

max

public static float max(float a,
                        float b)
                 throws ArithmeticException
Compute the maximum of two values

Parameters:
a - first value
b - second value
Returns:
b if a is lesser or equal to b, a otherwise
Throws:
ArithmeticException - thrown if a or b is NaN

max

public static double max(double a,
                         double b)
                  throws ArithmeticException
Compute the maximum of two values

Parameters:
a - first value
b - second value
Returns:
b if a is lesser or equal to b, a otherwise
Throws:
ArithmeticException - thrown if a or b is NaN

hypot

public static double hypot(double x,
                           double y)
                    throws ArithmeticException
Returns the hypotenuse of a triangle with sides x and y - sqrt(x2 +y2)
avoiding intermediate overflow or underflow.

Parameters:
x - a value
y - a value
Returns:
sqrt(x2 +y2)
Throws:
ArithmeticException - thrown if x or y is NaN

IEEEremainder

public static double IEEEremainder(double dividend,
                                   double divisor)
                            throws ArithmeticException
Computes the remainder as prescribed by the IEEE 754 standard. The remainder value is mathematically equal to x - y*n where n is the mathematical integer closest to the exact mathematical value of the quotient x/y. If two mathematical integers are equally close to x/y then n is the integer that is even.

Note: this implementation currently delegates to StrictMath.IEEEremainder(double, double)

Parameters:
dividend - the number to be divided
divisor - the number by which to divide
Returns:
the remainder, rounded
Throws:
ArithmeticException - thrown if input cannot allow to compute remainder

copySign

public static double copySign(double magnitude,
                              double sign)
Returns the first argument with the sign of the second argument. A NaN sign argument is treated as positive.

Parameters:
magnitude - the value to return
sign - the sign for the returned value
Returns:
the magnitude with the same sign as the sign argument
Throws:
ArithmeticException - thrown if magnitude is NaN

copySign

public static float copySign(float magnitude,
                             float sign)
Returns the first argument with the sign of the second argument. A NaN sign argument is treated as positive.

Parameters:
magnitude - the value to return
sign - the sign for the returned value
Returns:
the magnitude with the same sign as the sign argument
Throws:
ArithmeticException - thrown if magnitude is NaN

getExponent

public static int getExponent(double d)
Return the exponent of a double number, removing the bias.

For double numbers of the form 2x, the unbiased exponent is exactly x.

Parameters:
d - number from which exponent is requested
Returns:
exponent for d in IEEE754 representation, without bias

getExponent

public static int getExponent(float f)
Return the exponent of a float number, removing the bias.

For float numbers of the form 2x, the unbiased exponent is exactly x.

Parameters:
f - number from which exponent is requested
Returns:
exponent for d in IEEE754 representation, without bias

divide

public static double divide(double x,
                            double y)
                     throws ArithmeticException
Computes x / y

Parameters:
x - numerator
y - denominator
Returns:
x / y
Throws:
ArithmeticException - thrown if x / y = NaN

main

public static void main(String[] a)
Print out contents of arrays, and check the length.

used to generate the preset arrays originally.

Parameters:
a - unused


Copyright © 2017 CNES. All Rights Reserved.