Module org.apache.sis.util

Package org.apache.sis.math

Class MathFunctions

Object

Static

MathFunctions

public final class MathFunctions
extends Static

Simple mathematical functions in addition to the ones provided in Math. Some methods in this class are very similar to the standard Math methods or could be implemented with straightforward formulas. However, the methods in this class put an emphasis on:

• Rounding errors: magnitude, pow10.
• Distinguishing positive zero from negative zero: is­Positive, is­Negative, is­Same­Sign, xor­Sign.
• Distinguishing the different kinds of NaN numbers: to­Nan­Float, to­Nan­Ordinal.

Some additional functions not found in Math are: atanh, next­Prime­Number.

Since:

0.3

See Also:

• Decimal­Functions
• Numbers

Field Summary

Fields

Modifier and Type	Field	Description
static final int	HIGHEST_SUPPORTED_PRIME_NUMBER	The highest prime number supported by the next­Prime­Number(int) method.
static final double	LOG10_2	The logarithm of 2 in base 10, which is approximated by 0.3010299956639812.
static final int	MAX_NAN_ORDINAL	The maximal ordinal value for Na­N numbers created by to­Nan­Float(int).
static final int	MIN_NAN_ORDINAL	The minimal ordinal value for Na­N numbers created by to­Nan­Float(int).
static final double	SQRT_2	The square root of 2, which is approximated by 1.4142135623730951.

Method Summary

Modifier and Type	Method	Description
static double	acosh(double x)	Returns the inverse hyperbolic cosine of the given value.
static double	asinh(double x)	Returns the inverse hyperbolic sine of the given value.
static double	atanh(double x)	Returns the inverse hyperbolic tangent of the given value.
static double	average(long x, long y)	Computes the averages of two signed integers without overflow.
static int[]	common­Divisors(int... numbers)	Returns the positive divisors which are common to all the specified numbers.
static int[]	divisors(int number)	Returns the divisors of the specified number as positive integers.
static boolean	epsilon­Equal(double v1, double v2, double ε)	Returns true if the given values are equal or if their difference is not greater than the given threshold.
static boolean	epsilon­Equal(float v1, float v2, float ε)	Returns true if the given values are equal or if their difference is not greater than the given threshold.
static int	get­Exponent(double value)	Returns the unbiased exponent used in the representation of a double, with correction for sub-normal numbers.
static boolean	is­Negative(double value)	Returns true if the given value is negative, including negative zero.
static boolean	is­Negative­Zero(double value)	Returns true if the given value is the negative zero (-0.0).
static boolean	is­Positive(double value)	Returns true if the given value is positive, excluding negative zero.
static boolean	is­Positive­Zero(double value)	Returns true if the given value is the positive zero (+0.0).
static boolean	is­Same­Sign(double v1, double v2)	Returns true if the given values have the same sign, differentiating positive and negative zeros.
static double	magnitude(double... vector)	Returns the magnitude of the given vector.
static int	next­Prime­Number(int number)	Returns the first prime number equals or greater than the given value.
static double[]	polynomial­Roots(double... coefficients)	Returns the real (non-complex) roots of a polynomial equation having the given coefficients.
static long	pow(long base, int exponent)	Computes the result of base argument raised to the power given by exponent argument.
static double	pow10(double x)	Computes 10 raised to the power of x.
static double	pow10(int x)	Computes 10 raised to the power of x.
static double	quadruple­To­Double(long l0, long l1)	Converts two long bits values containing a IEEE 754 quadruple precision floating point number to a double precision floating point number.
static float	to­Nan­Float(int ordinal)	Returns a NaN number for the specified ordinal value.
static int	to­Nan­Ordinal(float value)	Returns the ordinal value of the given NaN number.
static double	truncate(double value)	Truncates the given value toward zero.
static double	xor­Sign(double value, double sign)	Returns the first floating-point argument with the sign reversed if the second floating-point argument is negative.

Methods inherited from class Object

clone, equals, finalize, get­Class, hash­Code, notify, notify­All, to­String, wait, wait, wait

Field Details

SQRT_2

public static final double SQRT_2

The square root of 2, which is approximated by 1.4142135623730951.

See Also:

• Math.sqrt(double)
• Constant Field Values

LOG10_2

public static final double LOG10_2

The logarithm of 2 in base 10, which is approximated by 0.3010299956639812. This constant is useful for converting a power of 2 to a power of 10 as below:

double exp10 = exp2 * LOG10_2;

Since:

0.4

See Also:

• Math.log10(double)
• get­Exponent(double)
• Constant Field Values

MIN_NAN_ORDINAL

public static final int MIN_NAN_ORDINAL

The minimal ordinal value for Na­N numbers created by to­Nan­Float(int). The current value is -2097152.

Since:

1.0

See Also:

• Constant Field Values

MAX_NAN_ORDINAL

public static final int MAX_NAN_ORDINAL

The maximal ordinal value for Na­N numbers created by to­Nan­Float(int). The current value is 2097151.

Since:

1.0

See Also:

• Constant Field Values

HIGHEST_SUPPORTED_PRIME_NUMBER

public static final int HIGHEST_SUPPORTED_PRIME_NUMBER

The highest prime number supported by the next­Prime­Number(int) method. In the current implementation, this value is 65521. However, this limit may change in any future Apache SIS version.

Implementation note

The current value is the highest prime number representable as an unsigned 16 bits integer. This is enough for current needs because 16 bits prime numbers are sufficient for finding the divisors of any 32 bits integers.

See Also:

• next­Prime­Number(int)
• Constant Field Values

Method Details

average

public static double average(long x,
 long y)

Computes the averages of two signed integers without overflow. The calculation is performed with long arithmetic before to convert the result to the double floating point number. This function may be more accurate than the classical (x+y)/2 formula when x and/or y are very large, because it will avoid the lost of last digits before averaging. If exactly one of x and y is odd, the result will contain the 0.5 fraction digit.

Reference

This function is adapted from The Aggregate Magic Algorithms from University of Kentucky.

Parameters:

x - the first value to average.

y - the second value to average.

Returns:

average of given values without integer overflow.

Since:

1.1

truncate

public static double truncate(double value)

Truncates the given value toward zero. Invoking this method is equivalent to invoking Math.floor(double) if the value is positive, or Math.ceil(double) if the value is negative.

Parameters:

value - the value to truncate.

Returns:

the largest in magnitude (further from zero) integer value which is equal or less in magnitude than the given value.

magnitude

public static double magnitude(double... vector)

Returns the magnitude of the given vector. This is defined by:

     sqrt(vector[0]² + vector[1]² + … + vector[length-1]²)

If the given vector contains a NaN value, then the result is NaN.

Implementation note

In the special case where only one element is different than zero, this method returns directly the absolute value of that element without computing sqrt(v²), in order to avoid rounding error. This special case has been implemented because this method is often invoked for computing the length of offset vectors, typically aligned with the axes of a Cartesian coordinate system.

Parameters:

vector - the vector for which to compute the magnitude.

Returns:

the magnitude of the given vector as a positive number, of NaN.

See Also:

• Math.hypot(double, double)

getExponent

public static int getExponent(double value)

Returns the unbiased exponent used in the representation of a double, with correction for sub-normal numbers. This method is related to Math.get­Exponent(double) in the following ways:

• For NaN and all values equal or greater than Double.MIN_NORMAL in magnitude (including infinities), this method returns results that are identical to Math.get­Exponent(double).
• For values smaller than Double.MIN_NORMAL in magnitude (including zero), the correction for sub-normal numbers results in return values smaller than what Math.get­Exponent(double) would return.

Special cases:

• If the argument is NaN or infinite, then the result is Double.MAX_EXPONENT + 1.
• If the argument is Double.MAX_VALUE, then the result is 1023.
• If the argument is Double.MIN_NORMAL, then the result is -1022.
• If the argument is Double.MIN_VALUE, then the result is -1074.
• If the argument is zero, then the result is -1075.

Identities

For any p values in the [-1075 … 1024] range and value = 2^p:

• get­Exponent(Math.scalb(1.0, p)) == p
• Math.scalb(1.0, get­Exponent(value)) == value
• Math.floor(LOG10_2 * get­Exponent(value)) == Math.floor(Math.log10(value))

Parameters:

value - the value for which to get the exponent.

Returns:

the unbiased exponent, corrected for sub-normal numbers if needed. Values will be in the [-1075 … 1024] range, inclusive.

Since:

0.4

See Also:

• Math.get­Exponent(double)
• Math.scalb(double, int)

pow

public static long pow(long base,
 int exponent)

Computes the result of base argument raised to the power given by exponent argument. This method computes the same value than Math.pow(double, double) but using only integer arithmetic. The result must be representable as a 64 bits integers (long primitive type), otherwise an Arithmetic­Exception is thrown. The result is guaranteed exact, in contrast to results represented as double floating point values which may be approximate for magnitudes greater than 2⁵². This method may also be faster.

The type of the base argument is long for convenience, since this method is used in contexts where relatively large integers are handled. However, any value greater than the capacity of int type is guaranteed to fail with Arithmetic­Exception unless exponent is 0 or 1. Likewise any exponent value greater than 62 is guaranteed to fail unless base is 0 or 1.

Reference

This method uses exponentiation by squaring technic.

Parameters:

base - the value to raise to an exponent.

exponent - the exponent, as zero or positive number.

Returns:

the value base^exponent as a 64 bits integer.

Throws:

Arithmetic­Exception - if the given exponent is negative, or if the result overflow integer arithmetic.

Since:

1.0

See Also:

• Math.pow(double, double)

pow10

public static double pow10(int x)

Computes 10 raised to the power of x. This method is faster and slightly more accurate than invoking Math.pow(10, x). Special cases:

• If x is equal or lower than -324, then the result is 0.
• If x is equal or greater than 309, then the result is positive infinity.
• If x is in the [0 … 18] range inclusive, then the result is exact.
• For all other x values, the result is the closest IEEE 754 approximation.

Purpose

This method has been defined because the standard Math.pow(10, x) method does not always return the closest IEEE floating point representation. Slight departures (1 or 2 ULP) are often allowed in math functions for performance reasons. The most accurate calculations are usually not necessary, but the base 10 is a special case since it is used for scaling axes or formatting human-readable output.

Parameters:

x - the exponent.

Returns:

10 raised to the given exponent.

See Also:

• pow10(double)
• LOG10_2
• Decimal­Functions

pow10

public static double pow10(double x)

Computes 10 raised to the power of x. Invoking this method is equivalent to invoking Math.pow(10, x), but is slightly more accurate in the special case where the given argument is an integer.

Parameters:

x - the exponent.

Returns:

10 raised to the given exponent.

See Also:

• pow10(int)
• Math.pow(double, double)
• Math.log10(double)

asinh

public static double asinh(double x)

Returns the inverse hyperbolic sine of the given value. This is the inverse of the Math.sinh(double) method.

Parameters:

x - the value for which to compute the inverse hyperbolic sine.

Returns:

the inverse hyperbolic sine of the given value.

Since:

0.6

See Also:

• Math.sinh(double)

acosh

public static double acosh(double x)

Returns the inverse hyperbolic cosine of the given value. This is the inverse of the Math.cosh(double) method.

Parameters:

x - the value for which to compute the inverse hyperbolic cosine.

Returns:

the inverse hyperbolic cosine of the given value.

Since:

0.6

See Also:

• Math.cosh(double)

atanh

public static double atanh(double x)

Returns the inverse hyperbolic tangent of the given value. This is the inverse of the Math.tanh(double) method. The range of input values shall be in the [-1 … 1]. Special cases:

• For x = NaN, this method returns a NaN value.
• For x = -1, this method returns negative infinity.
• For x = +1, this method returns positive infinity.

Parameters:

x - the value for which to compute the inverse hyperbolic tangent.

Returns:

the inverse hyperbolic tangent of the given value.

See Also:

• Math.tanh(double)

isPositive

public static boolean isPositive(double value)

Returns true if the given value is positive, excluding negative zero. Special cases:

• If the value is +0.0, returns true
• If the value is -0.0, returns false
• If the value is Na­N, returns false

As seen from the above cases, this method distinguishes positive zero from negative zero. The handling of zero values is the difference between invoking is­Positive(double) and testing if (value >= 0).

Parameters:

value - the value to test.

Returns:

true if the given value is positive, excluding negative zero.

See Also:

• is­Positive­Zero(double)
• is­Negative(double)

isPositiveZero

public static boolean isPositiveZero(double value)

Returns true if the given value is the positive zero (+0.0). This method returns false for the negative zero (-0.0). This method is equivalent to the following code, but potentially faster:

return (value == 0) && isPositive(value);

Parameters:

value - the value to test.

Returns:

true if the given value is +0.0 (not -0.0).

Since:

0.4

See Also:

• is­Positive(double)
• is­Negative­Zero(double)

isNegative

public static boolean isNegative(double value)

Returns true if the given value is negative, including negative zero. Special cases:

• If the value is +0.0, returns false
• If the value is -0.0, returns true
• If the value is Na­N, returns false

As seen from the above cases, this method distinguishes positive zero from negative zero. The handling of zero values is the difference between invoking is­Negative(double) and testing if (value < 0).

Parameters:

value - the value to test.

Returns:

true if the given value is negative, including negative zero.

See Also:

• is­Negative­Zero(double)
• is­Positive(double)

isNegativeZero

public static boolean isNegativeZero(double value)

Returns true if the given value is the negative zero (-0.0). This method returns false for the positive zero (+0.0). This method is equivalent to the following code, but potentially faster:

return (value == 0) && isNegative(value);

Parameters:

value - the value to test.

Returns:

true if the given value is -0.0 (not +0.0).

Since:

0.4

See Also:

• is­Negative(double)
• is­Positive­Zero(double)

isSameSign

public static boolean isSameSign(double v1,
 double v2)

Returns true if the given values have the same sign, differentiating positive and negative zeros. Special cases:

• +0.0 and -0.0 are considered to have opposite sign
• If any value is Na­N, returns false

Parameters:

v1 - the first value.

v2 - the second value, to compare the sign with the first value.

Returns:

true if the given values are not NaN and have the same sign.

See Also:

• Math.signum(double)

xorSign

public static double xorSign(double value,
 double sign)

Returns the first floating-point argument with the sign reversed if the second floating-point argument is negative. This method is similar to Math.copy­Sign(value, sign) except that the sign is combined with an exclusive or operation instead of being copied.

This method makes no guarantee about whether Na­N values are handled as positive or negative numbers. This is the same policy than Math.copy­Sign(double, double).

Parameters:

value - the parameter providing the value that may need a sign change.

sign - the parameter providing the sign to xor with the value.

Returns:

the provided value with its sign reversed if the sign parameter is negative.

See Also:

• Math.copy­Sign(double, double)

epsilonEqual

public static boolean epsilonEqual(float v1,
 float v2,
 float ε)

Returns true if the given values are equal or if their difference is not greater than the given threshold. More specifically:

• If both values are positive infinity, or if both values are negative infinity, then this method returns true.
• If both values are NaN, then this method returns true. Note that this method does not differentiate the various NaN values.
• Otherwise, this method returns the result of the abs(v1 - v2) <= ε comparison.

Parameters:

v1 - the first value to compare.

v2 - the second value to compare.

ε - the tolerance threshold, which must be positive.

Returns:

true if both values are equal given the tolerance threshold.

epsilonEqual

public static boolean epsilonEqual(double v1,
 double v2,
 double ε)

Returns true if the given values are equal or if their difference is not greater than the given threshold. More specifically:

• If both values are positive infinity, or if both values are negative infinity, then this method returns true.
• If both values are NaN, then this method returns true. Note that this method does not differentiate the various NaN values.
• Otherwise, this method returns the result of the abs(v1 - v2) <= ε comparison.

Parameters:

v1 - the first value to compare.

v2 - the second value to compare.

ε - the tolerance threshold, which must be positive.

Returns:

true if both values are equal given the tolerance threshold.

toNanFloat

public static float toNanFloat(int ordinal)
                        throws IllegalArgumentException

Returns a NaN number for the specified ordinal value. Valid NaN numbers in Java can have bit fields in the ranges listed below:

• [0x7F800001 … 0x7FFFFFFF], with 0x7FC00000 as the bit fields of the standard Float.Na­N value
• [0x­FF800001 … 0x­FFFFFFFF]

Some of those bits, named the payload, can be used for storing custom information. This method maps some of the payload values to each ordinal value.

This method guarantees that to­Nan­Float(0) returns the standard Float.Na­N value. For all other ordinal values, the relationship to the payload values is implementation dependent and may change in any future version of the SIS library. The current implementation restricts the range of allowed ordinal values to a smaller one than the range of all possible values.

Parameters:

ordinal - the NaN ordinal value, from -2097152 to 2097151 inclusive.

Returns:

one of the legal NaN values as a float.

Throws:

Illegal­Argument­Exception - if the specified ordinal is out of range.

See Also:

• Float.int­Bits­To­Float(int)

toNanOrdinal

public static int toNanOrdinal(float value)
                        throws IllegalArgumentException

Returns the ordinal value of the given NaN number. This method is the converse of to­Nan­Float(int).

If the given float is the standard Float.Na­N value, then this method returns 0. For all other values, the relationship between the float payload and the returned ordinal is implementation dependent and may change in any future Apache SIS version.

Parameters:

value - the value from which to get the NaN ordinal value.

Returns:

the NaN ordinal value of the given floating point value.

Throws:

Illegal­Argument­Exception - if the given value is not a NaN value, or does not use a supported bits pattern.

quadrupleToDouble

public static double quadrupleToDouble(long l0,
 long l1)

Converts two long bits values containing a IEEE 754 quadruple precision floating point number to a double precision floating point number. About 17 decimal digits of precision may be lost due to the double type having only half the capacity of quadruple precision type.

Some quadruple precision values cannot be represented in double precision and are mapped to double values as below:

• Values having a magnitude less than Double.MIN_VALUE are mapped to positive or negative zero.
• Values having a magnitude greater than Double.MAX_VALUE are mapped to Double.POSITIVE_INFINITY or Double.NEGATIVE_INFINITY.
• All NaN values are currently collapsed to the single "canonical" Double.Na­N value (this policy may be revisited in future SIS version).

Parameters:

l0 - upper part of the quadruple precision floating point number.

l1 - lower part of the quadruple precision floating point number.

Returns:

double precision approximation.

Since:

0.7

See Also:

• Quadruple-precision floating-point format on Wikipedia

nextPrimeNumber

public static int nextPrimeNumber(int number)
                           throws IllegalArgumentException

Returns the first prime number equals or greater than the given value. Current implementation accepts only values in the [2 … 65521] range.

Parameters:

number - the number for which to find the next prime.

Returns:

the given number if it is a prime number, or the next prime number otherwise.

Throws:

Illegal­Argument­Exception - if the given value is outside the supported range.

See Also:

• Big­Integer.is­Probable­Prime(int)

divisors

public static int[] divisors(int number)

Returns the divisors of the specified number as positive integers. For any value other than O (which returns an empty array), the first element in the returned array is always 1 and the last element is always the absolute value of number.

Parameters:

number - the number for which to compute the divisors.

Returns:

the divisors in strictly increasing order.

commonDivisors

public static int[] commonDivisors(int... numbers)

Returns the positive divisors which are common to all the specified numbers. The returned array always starts with value 1, unless the given value is 0 in which case this method returns an empty array.

Parameters:

numbers - the numbers for which to compute the divisors, in any order.

Returns:

the divisors common to all the given numbers, in strictly increasing order.

polynomialRoots

public static double[] polynomialRoots(double... coefficients)

Returns the real (non-complex) roots of a polynomial equation having the given coefficients. This method returns the x values for which y=0 in the following equation:

y = c₀ + c₁⋅x + c₂⋅x² + c₃⋅x³ + … + c_n⋅xⁿ

Current implementation can resolve polynomials described by a maximum of 5 coefficients, ignoring leading and trailing zeros. They correspond to linear, quadratic, cubic and quartic polynomials.

Parameters:

coefficients - the c₀, c₁, c₂, … c_n coefficients, in that order.

Returns:

the non-complex roots, or an empty array if none.

Throws:

Unsupported­Operation­Exception - if given arguments contain more non-zero coefficients than this method can handle.

Since:

1.0

See Also:

• Quad­Curve2D.solve­Quadratic(double[])
• Cubic­Curve2D.solve­Cubic(double[])