org.apfloat
Class ApfloatMath

java.lang.Object
  extended by org.apfloat.ApfloatMath

public class ApfloatMath
extends Object

Various mathematical functions for arbitrary precision floating-point numbers.

Due to different types of round-off errors that can occur in the implementation, no guarantees about e.g. monotonicity are given for any of the methods.

Version:
1.5
Author:
Mikko Tommila
See Also:
ApintMath

Method Summary
static Apfloat abs(Apfloat x)
          Absolute value.
static Apfloat acos(Apfloat x)
          Inverse cosine.
static Apfloat acosh(Apfloat x)
          Inverse hyperbolic cosine.
static Apfloat agm(Apfloat a, Apfloat b)
          Arithmetic-geometric mean.
static Apfloat asin(Apfloat x)
          Inverse sine.
static Apfloat asinh(Apfloat x)
          Inverse hyperbolic sine.
static Apfloat atan(Apfloat x)
          Inverse tangent.
static Apfloat atan2(Apfloat x, Apfloat y)
          Converts cartesian coordinates to polar coordinates.
static Apfloat atanh(Apfloat x)
          Inverse hyperbolic tangent.
static Apfloat cbrt(Apfloat x)
          Cube root.
static Apint ceil(Apfloat x)
          Ceiling function.
static Apfloat copySign(Apfloat x, Apfloat y)
          Copy sign from one argument to another.
static Apfloat cos(Apfloat x)
          Cosine.
static Apfloat cosh(Apfloat x)
          Hyperbolic cosine.
static Apfloat exp(Apfloat x)
          Exponent function.
static Apint floor(Apfloat x)
          Floor function.
static Apfloat fmod(Apfloat x, Apfloat y)
          Returns x modulo y.
static Apfloat inverseRoot(Apfloat x, long n)
          Inverse positive integer root.
static Apfloat inverseRoot(Apfloat x, long n, long targetPrecision)
          Inverse positive integer root.
static Apfloat inverseRoot(Apfloat x, long n, long targetPrecision, Apfloat initialGuess)
          Inverse positive integer root.
static Apfloat inverseRoot(Apfloat x, long n, long targetPrecision, Apfloat initialGuess, long initialPrecision)
          Inverse positive integer root.
static Apfloat log(Apfloat x)
          Natural logarithm.
static Apfloat logRadix(long precision, int radix)
          Gets or calculates logarithm of a radix to required precision.
static Apfloat[] modf(Apfloat x)
          Split to integer and fractional parts.
static Apfloat multiplyAdd(Apfloat a, Apfloat b, Apfloat c, Apfloat d)
          Fused multiply-add.
static Apfloat multiplySubtract(Apfloat a, Apfloat b, Apfloat c, Apfloat d)
          Fused multiply-subtract.
static Apfloat negate(Apfloat x)
          Deprecated. Use Apfloat.negate().
static Apfloat pi(long precision)
          Calculates π.
static Apfloat pi(long precision, int radix)
          Calculates π.
static Apfloat pow(Apfloat x, Apfloat y)
          Arbitrary power.
static Apfloat pow(Apfloat x, long n)
          Integer power.
static Apfloat product(Apfloat... x)
          Product of numbers.
static Apfloat root(Apfloat x, long n)
          Positive integer root.
static Apfloat scale(Apfloat x, long scale)
          Multiply by a power of the radix.
static Apfloat sin(Apfloat x)
          Sine.
static Apfloat sinh(Apfloat x)
          Hyperbolic sine.
static Apfloat sqrt(Apfloat x)
          Square root.
static Apfloat sum(Apfloat... x)
          Sum of numbers.
static Apfloat tan(Apfloat x)
          Tangent.
static Apfloat tanh(Apfloat x)
          Hyperbolic tangent.
static Apint truncate(Apfloat x)
          Truncates fractional part.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

pow

public static Apfloat pow(Apfloat x,
                          long n)
                   throws ArithmeticException,
                          ApfloatRuntimeException
Integer power.

Parameters:
x - Base of the power operator.
n - Exponent of the power operator.
Returns:
x to the n:th power, that is xn.
Throws:
ArithmeticException - If both x and n are zero.
ApfloatRuntimeException

sqrt

public static Apfloat sqrt(Apfloat x)
                    throws ArithmeticException,
                           ApfloatRuntimeException
Square root.

Parameters:
x - The argument.
Returns:
Square root of x.
Throws:
ArithmeticException - If x is negative.
ApfloatRuntimeException

cbrt

public static Apfloat cbrt(Apfloat x)
                    throws ApfloatRuntimeException
Cube root.

Parameters:
x - The argument.
Returns:
Cube root of x.
Throws:
ApfloatRuntimeException

root

public static Apfloat root(Apfloat x,
                           long n)
                    throws ArithmeticException,
                           ApfloatRuntimeException
Positive integer root.

Parameters:
x - The argument.
n - Which root to take.
Returns:
n:th root of x, that is x1/n.
Throws:
ArithmeticException - If n is zero, or x is negative and n is even.
ApfloatRuntimeException

inverseRoot

public static Apfloat inverseRoot(Apfloat x,
                                  long n)
                           throws ArithmeticException,
                                  ApfloatRuntimeException
Inverse positive integer root.

Parameters:
x - The argument.
n - Which inverse root to take.
Returns:
Inverse n:th root of x, that is x-1/n.
Throws:
ArithmeticException - If x or n is zero, or x is negative and n is even.
ApfloatRuntimeException

inverseRoot

public static Apfloat inverseRoot(Apfloat x,
                                  long n,
                                  long targetPrecision)
                           throws IllegalArgumentException,
                                  ArithmeticException,
                                  ApfloatRuntimeException
Inverse positive integer root.

Parameters:
x - The argument.
n - Which inverse root to take.
targetPrecision - Precision of the desired result.
Returns:
Inverse n:th root of x, that is x-1/n.
Throws:
IllegalArgumentException - If targetPrecision <= 0.
ArithmeticException - If x or n is zero, or x is negative and n is even.
ApfloatRuntimeException

inverseRoot

public static Apfloat inverseRoot(Apfloat x,
                                  long n,
                                  long targetPrecision,
                                  Apfloat initialGuess)
                           throws IllegalArgumentException,
                                  ArithmeticException,
                                  ApfloatRuntimeException
Inverse positive integer root.

Parameters:
x - The argument.
n - Which inverse root to take.
targetPrecision - Precision of the desired result.
initialGuess - Initial guess for the result value, or null if none is available.
Returns:
Inverse n:th root of x, that is x-1/n.
Throws:
IllegalArgumentException - If targetPrecision <= 0.
ArithmeticException - If x or n is zero, or x is negative and n is even.
ApfloatRuntimeException

inverseRoot

public static Apfloat inverseRoot(Apfloat x,
                                  long n,
                                  long targetPrecision,
                                  Apfloat initialGuess,
                                  long initialPrecision)
                           throws IllegalArgumentException,
                                  ArithmeticException,
                                  ApfloatRuntimeException
Inverse positive integer root.

This method is the basis for most of apfloat's non-elementary operations. It is used e.g. in Apfloat.divide(Apfloat), sqrt(Apfloat) and root(Apfloat,long).

Parameters:
x - The argument.
n - Which inverse root to take.
targetPrecision - Precision of the desired result.
initialGuess - Initial guess for the result value, or null if none is available.
initialPrecision - Precision of the initial guess, if available.
Returns:
Inverse n:th root of x, that is x-1/n.
Throws:
IllegalArgumentException - If targetPrecision <= 0 or initialPrecision <= 0.
ArithmeticException - If x or n is zero, or x is negative and n is even.
ApfloatRuntimeException

floor

public static Apint floor(Apfloat x)
                   throws ApfloatRuntimeException
Floor function. Returns the largest (closest to positive infinity) value that is not greater than the argument and is equal to a mathematical integer.

Parameters:
x - The argument.
Returns:
x rounded towards negative infinity.
Throws:
ApfloatRuntimeException

ceil

public static Apint ceil(Apfloat x)
                  throws ApfloatRuntimeException
Ceiling function. Returns the smallest (closest to negative infinity) value that is not less than the argument and is equal to a mathematical integer.

Parameters:
x - The argument.
Returns:
x rounded towards positive infinity.
Throws:
ApfloatRuntimeException

truncate

public static Apint truncate(Apfloat x)
                      throws ApfloatRuntimeException
Truncates fractional part.

Parameters:
x - The argument.
Returns:
x rounded towards zero.
Throws:
ApfloatRuntimeException

negate

@Deprecated
public static Apfloat negate(Apfloat x)
                      throws ApfloatRuntimeException
Deprecated. Use Apfloat.negate().

Returns an apfloat whose value is -x.

Parameters:
x - The argument.
Returns:
-x.
Throws:
ApfloatRuntimeException

abs

public static Apfloat abs(Apfloat x)
                   throws ApfloatRuntimeException
Absolute value.

Parameters:
x - The argument.
Returns:
Absolute value of x.
Throws:
ApfloatRuntimeException

copySign

public static Apfloat copySign(Apfloat x,
                               Apfloat y)
                        throws ApfloatRuntimeException
Copy sign from one argument to another.

Parameters:
x - The value whose sign is to be adjusted.
y - The value whose sign is to be used.
Returns:
x with its sign changed to match the sign of y.
Throws:
ApfloatRuntimeException
Since:
1.1

scale

public static Apfloat scale(Apfloat x,
                            long scale)
                     throws ApfloatRuntimeException
Multiply by a power of the radix.

Parameters:
x - The argument.
scale - The scaling factor.
Returns:
x * x.radix()scale.
Throws:
ApfloatRuntimeException

modf

public static Apfloat[] modf(Apfloat x)
                      throws ApfloatRuntimeException
Split to integer and fractional parts. The integer part is simply i = floor(x). For the fractional part f the following is always true:

0 <= f < 1

Parameters:
x - The argument.
Returns:
An array of two apfloats, [i, f], the first being the integer part and the last being the fractional part.
Throws:
ApfloatRuntimeException

fmod

public static Apfloat fmod(Apfloat x,
                           Apfloat y)
                    throws ApfloatRuntimeException
Returns x modulo y.

This function calculates the remainder f of x / y such that x = i * y + f, where i is an integer, f has the same sign as x, and the absolute value of f is less than the absolute value of y.

If y is zero, then zero is returned.

Parameters:
x - The dividend.
y - The divisor.
Returns:
The remainder when x is divided by y.
Throws:
ApfloatRuntimeException

multiplyAdd

public static Apfloat multiplyAdd(Apfloat a,
                                  Apfloat b,
                                  Apfloat c,
                                  Apfloat d)
                           throws ApfloatRuntimeException
Fused multiply-add. Calculates a * b + c * d so that the precision used in the multiplications is only what is needed for the end result. Performance can this way be better than by calculating a.multiply(b).add(c.multiply(d)).

Parameters:
a - First argument.
b - Second argument.
c - Third argument.
d - Fourth argument.
Returns:
a * b + c * d.
Throws:
ApfloatRuntimeException

multiplySubtract

public static Apfloat multiplySubtract(Apfloat a,
                                       Apfloat b,
                                       Apfloat c,
                                       Apfloat d)
                                throws ApfloatRuntimeException
Fused multiply-subtract. Calculates a * b - c * d so that the precision used in the multiplications is only what is needed for the end result. Performance can this way be better than by calculating a.multiply(b).subtract(c.multiply(d)).

Parameters:
a - First argument.
b - Second argument.
c - Third argument.
d - Fourth argument.
Returns:
a * b - c * d.
Throws:
ApfloatRuntimeException

agm

public static Apfloat agm(Apfloat a,
                          Apfloat b)
                   throws ApfloatRuntimeException
Arithmetic-geometric mean.

Parameters:
a - First argument.
b - Second argument.
Returns:
Arithmetic-geometric mean of a and b.
Throws:
ApfloatRuntimeException

pi

public static Apfloat pi(long precision)
                  throws IllegalArgumentException,
                         NumberFormatException,
                         ApfloatRuntimeException
Calculates π. Uses default radix.

Parameters:
precision - Number of digits of π to calculate.
Returns:
π accurate to precision digits, in the default radix.
Throws:
NumberFormatException - If the default radix is not valid.
IllegalArgumentException - In case the precision is invalid.
ApfloatRuntimeException

pi

public static Apfloat pi(long precision,
                         int radix)
                  throws IllegalArgumentException,
                         NumberFormatException,
                         ApfloatRuntimeException
Calculates π.

Parameters:
precision - Number of digits of π to calculate.
radix - The radix in which the number should be presented.
Returns:
π accurate to precision digits, in base radix.
Throws:
NumberFormatException - If the radix is not valid.
IllegalArgumentException - In case the precision is invalid.
ApfloatRuntimeException

log

public static Apfloat log(Apfloat x)
                   throws ArithmeticException,
                          ApfloatRuntimeException
Natural logarithm.

The logarithm is calculated using the arithmetic-geometric mean. See the Borweins' book for the formula.

Parameters:
x - The argument.
Returns:
Natural logarithm of x.
Throws:
ArithmeticException - If x <= 0.
ApfloatRuntimeException

logRadix

public static Apfloat logRadix(long precision,
                               int radix)
                        throws ApfloatRuntimeException
Gets or calculates logarithm of a radix to required precision. The calculated value is stored in a cache for later usage.

Parameters:
precision - The needed precision.
radix - The radix.
Returns:
Natural logarithm of radix to the specified precision.
Throws:
NumberFormatException - If the radix is invalid.
ApfloatRuntimeException

exp

public static Apfloat exp(Apfloat x)
                   throws ApfloatRuntimeException
Exponent function. Calculated using Newton's iteration for the inverse of logarithm.

Parameters:
x - The argument.
Returns:
ex.
Throws:
ApfloatRuntimeException

pow

public static Apfloat pow(Apfloat x,
                          Apfloat y)
                   throws ArithmeticException,
                          ApfloatRuntimeException
Arbitrary power. Calculated using log() and exp().

This method doesn't calculate the result properly if x is negative and y is an integer. For that you should use pow(Apfloat,long).

Parameters:
x - The base.
y - The exponent.
Returns:
xy.
Throws:
ArithmeticException - If both x and y are zero, or x is negative.
ApfloatRuntimeException

acosh

public static Apfloat acosh(Apfloat x)
                     throws ArithmeticException,
                            ApfloatRuntimeException
Inverse hyperbolic cosine. Calculated using log().

Parameters:
x - The argument.
Returns:
Inverse hyperbolic cosine of x.
Throws:
ArithmeticException - If x < 1.
ApfloatRuntimeException

asinh

public static Apfloat asinh(Apfloat x)
                     throws ApfloatRuntimeException
Inverse hyperbolic sine. Calculated using log().

Parameters:
x - The argument.
Returns:
Inverse hyperbolic sine of x.
Throws:
ApfloatRuntimeException

atanh

public static Apfloat atanh(Apfloat x)
                     throws ArithmeticException,
                            ApfloatRuntimeException
Inverse hyperbolic tangent. Calculated using log().

Parameters:
x - The argument.
Returns:
Inverse hyperbolic tangent of x.
Throws:
ArithmeticException - If abs(x) >= 1.
ApfloatRuntimeException

cosh

public static Apfloat cosh(Apfloat x)
                    throws ApfloatRuntimeException
Hyperbolic cosine. Calculated using exp().

Parameters:
x - The argument.
Returns:
Hyperbolic cosine of x.
Throws:
ApfloatRuntimeException

sinh

public static Apfloat sinh(Apfloat x)
                    throws ApfloatRuntimeException
Hyperbolic sine. Calculated using exp().

Parameters:
x - The argument.
Returns:
Hyperbolic sine of x.
Throws:
ApfloatRuntimeException

tanh

public static Apfloat tanh(Apfloat x)
                    throws ApfloatRuntimeException
Hyperbolic tangent. Calculated using exp().

Parameters:
x - The argument.
Returns:
Hyperbolic tangent of x.
Throws:
ApfloatRuntimeException

acos

public static Apfloat acos(Apfloat x)
                    throws ArithmeticException,
                           ApfloatRuntimeException
Inverse cosine. Calculated using complex functions.

Parameters:
x - The argument.
Returns:
Inverse cosine of x.
Throws:
ArithmeticException - If abs(x) > 1.
ApfloatRuntimeException

asin

public static Apfloat asin(Apfloat x)
                    throws ArithmeticException,
                           ApfloatRuntimeException
Inverse sine. Calculated using complex functions.

Parameters:
x - The argument.
Returns:
Inverse sine of x.
Throws:
ArithmeticException - If abs(x) > 1.
ApfloatRuntimeException

atan

public static Apfloat atan(Apfloat x)
                    throws ApfloatRuntimeException
Inverse tangent. Calculated using complex functions.

Parameters:
x - The argument.
Returns:
Inverse tangent of x.
Throws:
ApfloatRuntimeException

atan2

public static Apfloat atan2(Apfloat x,
                            Apfloat y)
                     throws ArithmeticException,
                            ApfloatRuntimeException
Converts cartesian coordinates to polar coordinates. Calculated using complex functions.

Computes the phase angle by computing an arc tangent of x/y in the range of -π < angle <= π.

Parameters:
x - The argument.
y - The argument.
Returns:
The angle of the point (y, x) in the plane.
Throws:
ArithmeticException - If x and y are both zero.
ApfloatRuntimeException

cos

public static Apfloat cos(Apfloat x)
                   throws ApfloatRuntimeException
Cosine. Calculated using complex functions.

Parameters:
x - The argument.
Returns:
Cosine of x.
Throws:
ApfloatRuntimeException

sin

public static Apfloat sin(Apfloat x)
                   throws ApfloatRuntimeException
Sine. Calculated using complex functions.

Parameters:
x - The argument.
Returns:
Sine of x.
Throws:
ApfloatRuntimeException

tan

public static Apfloat tan(Apfloat x)
                   throws ArithmeticException,
                          ApfloatRuntimeException
Tangent. Calculated using complex functions.

Parameters:
x - The argument.
Returns:
Tangent of x.
Throws:
ArithmeticException - If x is π/2 + n π where n is an integer.
ApfloatRuntimeException

product

public static Apfloat product(Apfloat... x)
                       throws ApfloatRuntimeException
Product of numbers. The precision used in the multiplications is only what is needed for the end result. This method may perform significantly better than simply multiplying the numbers sequentially.

If there are no arguments, the return value is 1.

Parameters:
x - The argument(s).
Returns:
The product of the given numbers.
Throws:
ApfloatRuntimeException
Since:
1.3

sum

public static Apfloat sum(Apfloat... x)
                   throws ApfloatRuntimeException
Sum of numbers. The precision used in the additions is only what is needed for the end result. This method may perform significantly better than simply adding the numbers sequentially.

If there are no arguments, the return value is 0.

Parameters:
x - The argument(s).
Returns:
The sum of the given numbers.
Throws:
ApfloatRuntimeException
Since:
1.3