org.apfloat

Class ApfloatMath

java.lang.Object

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.8.2

Author:

Mikko Tommila

See Also:

ApintMath

Method Summary

Modifier and Type	Method and Description
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	frac(Apfloat x) Extracts fractional part.
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	log(Apfloat x, Apfloat b) Logarithm in arbitrary base.
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	round(Apfloat x, long precision, RoundingMode roundingMode) Rounds the given number to the specified precision with the specified rounding mode.
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 Apfloat	toDegrees(Apfloat x) Converts an angle measured in radians to degrees.
static Apfloat	toRadians(Apfloat x) Converts an angle measured in degrees to radians.
static Apint	truncate(Apfloat x) Truncates fractional part.
static Apfloat	w(Apfloat x) Lambert W function.

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

frac

public static Apfloat frac(Apfloat x)
                    throws ApfloatRuntimeException

Extracts fractional part.

Parameters:

x - The argument.

Returns:

The fractional part of x.

Throws:

ApfloatRuntimeException

Since:

1.7.0

round

public static Apfloat round(Apfloat x,
                            long precision,
                            RoundingMode roundingMode)
                     throws IllegalArgumentException,
                            ArithmeticException,
                            ApfloatRuntimeException

Rounds the given number to the specified precision with the specified rounding mode.

Parameters:

x - The number to round.

precision - The precision to round to.

roundingMode - The rounding mode to use.

Returns:

The rounded number.

Throws:

IllegalArgumentException - If precision is less than zero or zero.

ArithmeticException - If rounding is necessary (result is not exact) and rounding mode is RoundingMode.UNNECESSARY.

ApfloatRuntimeException

Since:

1.7.0

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

log

public static Apfloat log(Apfloat x,
                          Apfloat b)
                   throws ArithmeticException,
                          ApfloatRuntimeException

Logarithm in arbitrary base.

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

Parameters:

x - The argument.

b - The base.

Returns:

Base-b logarithm of x.

Throws:

ArithmeticException - If x <= 0 or b <= 0.

ApfloatRuntimeException

Since:

1.6

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 (in radians).

Returns:

Cosine of x.

Throws:

ApfloatRuntimeException

sin

public static Apfloat sin(Apfloat x)
                   throws ApfloatRuntimeException

Sine. Calculated using complex functions.

Parameters:

x - The argument (in radians).

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 (in radians).

Returns:

Tangent of x.

Throws:

ArithmeticException - If x is π/2 + n π where n is an integer.

ApfloatRuntimeException

w

public static Apfloat w(Apfloat x)
                 throws ArithmeticException,
                        ApfloatRuntimeException

Lambert W function. The W function gives the solution to the equation W eW = x. Also known as the product logarithm.

This function only gives the solution to the principal branch, W₀. For the real-valued W_-1 branch, use ApcomplexMath.w(Apcomplex,long).

Parameters:

x - The argument.

Returns:

W0(x).

Throws:

ArithmeticException - If x is less than -1/e.

ApfloatRuntimeException

Since:

1.8.0

toDegrees

public static Apfloat toDegrees(Apfloat x)
                         throws ApfloatRuntimeException

Converts an angle measured in radians to degrees.

Parameters:

x - The angle, in radians.

Returns:

The angle in degrees.

Throws:

ApfloatRuntimeException

Since:

1.8.0

toRadians

public static Apfloat toRadians(Apfloat x)
                         throws ApfloatRuntimeException

Converts an angle measured in degrees to radians.

Parameters:

x - The angle, in degrees.

Returns:

The angle in radians.

Throws:

ApfloatRuntimeException

Since:

1.8.0

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