Class DD
- All Implemented Interfaces:
Serializable
,Cloneable
,Comparable
A DoubleDouble uses a representation containing two double-precision values. A number x is represented as a pair of doubles, x.hi and x.lo, such that the number represented by x is x.hi + x.lo, where
|x.lo| <= 0.5*ulp(x.hi)and ulp(y) means "unit in the last place of y". The basic arithmetic operations are implemented using convenient properties of IEEE-754 floating-point arithmetic.
The range of values which can be represented is the same as in IEEE-754. The precision of the representable numbers is twice as great as IEEE-754 double precision.
The correctness of the arithmetic algorithms relies on operations being performed with standard IEEE-754 double precision and rounding. This is the Java standard arithmetic model, but for performance reasons Java implementations are not constrained to using this standard by default. Some processors (notably the Intel Pentium architecture) perform floating point operations in (non-IEEE-754-standard) extended-precision. A JVM implementation may choose to use the non-standard extended-precision as its default arithmetic mode. To prevent this from happening, this code uses the Java strictfp modifier, which forces all operations to take place in the standard IEEE-754 rounding model.
The API provides both a set of value-oriented operations and a set of mutating operations. Value-oriented operations treat DoubleDouble values as immutable; operations on them return new objects carrying the result of the operation. This provides a simple and safe semantics for writing DoubleDouble expressions. However, there is a performance penalty for the object allocations required. The mutable interface updates object values in-place. It provides optimum memory performance, but requires care to ensure that aliasing errors are not created and constant values are not changed.
For example, the following code example constructs three DD instances: two to hold the input values and one to hold the result of the addition.
DD a = new DD(2.0); DD b = new DD(3.0); DD c = a.add(b);In contrast, the following approach uses only one object:
DD a = new DD(2.0); a.selfAdd(3.0);
This implementation uses algorithms originally designed variously by Knuth, Kahan, Dekker, and Linnainmaa. Douglas Priest developed the first C implementation of these techniques. Other more recent C++ implementation are due to Keith M. Briggs and David Bailey et al.
References
- Priest, D., Algorithms for Arbitrary Precision Floating Point Arithmetic, in P. Kornerup and D. Matula, Eds., Proc. 10th Symposium on Computer Arithmetic, IEEE Computer Society Press, Los Alamitos, Calif., 1991.
- Yozo Hida, Xiaoye S. Li and David H. Bailey, Quad-Double Arithmetic: Algorithms, Implementation, and Application, manuscript, Oct 2000; Lawrence Berkeley National Laboratory Report BNL-46996.
- David Bailey, High Precision Software Directory; http://crd.lbl.gov/~dhbailey/mpdist/index.html
- Author:
- Martin Davis
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final DD
The value nearest to the constant e (the natural logarithm base).static final double
The smallest representable relative difference between two {link @ DoubleDouble} valuesstatic final DD
A value representing the result of an operation which does not return a valid number.static final DD
The value nearest to the constant Pi.static final DD
The value nearest to the constant Pi / 2.static final DD
The value nearest to the constant 2 * Pi. -
Constructor Summary
ConstructorsConstructorDescriptionDD()
Creates a new DoubleDouble with value 0.0.DD
(double x) Creates a new DoubleDouble with value x.DD
(double hi, double lo) Creates a new DoubleDouble with value (hi, lo).Creates a new DoubleDouble with value equal to the argument.Creates a new DoubleDouble with value equal to the argument. -
Method Summary
Modifier and TypeMethodDescriptionabs()
Returns the absolute value of this value.final DD
add
(double y) Returns a new DoubleDouble whose value is (this + y).final DD
Returns a new DoubleDouble whose value is (this + y).ceil()
Returns the smallest (closest to negative infinity) value that is not less than the argument and is equal to a mathematical integer.clone()
Creates and returns a copy of this value.int
Compares two DoubleDouble objects numerically.static DD
Creates a new DoubleDouble with the value of the argument.static DD
determinant
(double x1, double y1, double x2, double y2) Computes the determinant of the 2x2 matrix with the given entries.static DD
determinant
(DD x1, DD y1, DD x2, DD y2) Computes the determinant of the 2x2 matrix with the given entries.final DD
divide
(double y) Computes a new DoubleDouble whose value is (this / y).final DD
Computes a new DoubleDouble whose value is (this / y).double
Converts this value to the nearest double-precision number.dump()
Dumps the components of this number to a string.boolean
Tests whether this value is equal to another DoubleDouble value.floor()
Returns the largest (closest to positive infinity) value that is not greater than the argument and is equal to a mathematical integer.boolean
Tests whether this value is greater than or equals to another DoubleDouble value.boolean
Tests whether this value is greater than another DoubleDouble value.int
intValue()
Converts this value to the nearest integer.boolean
isNaN()
Tests whether this value is NaN.boolean
Tests whether this value is less than 0.boolean
Tests whether this value is greater than 0.boolean
isZero()
Tests whether this value is equal to 0.boolean
Tests whether this value is less than or equal to another DoubleDouble value.boolean
Tests whether this value is less than another DoubleDouble value.Computes the maximum of this and another DD number.Computes the minimum of this and another DD number.final DD
multiply
(double y) Returns a new DoubleDouble whose value is (this * y).final DD
Returns a new DoubleDouble whose value is (this * y).final DD
negate()
Returns a new DoubleDouble whose value is -this.static DD
Converts a string representation of a real number into a DoubleDouble value.pow
(int exp) Computes the value of this number raised to an integral power.final DD
Returns a DoubleDouble whose value is 1 / this.rint()
Rounds this value to the nearest integer.final DD
selfAdd
(double y) Adds the argument to the value of this.final DD
Adds the argument to the value of this.final DD
selfDivide
(double y) Divides this object by the argument, returning this.final DD
selfDivide
(DD y) Divides this object by the argument, returning this.final DD
selfMultiply
(double y) Multiplies this object by the argument, returning this.final DD
selfMultiply
(DD y) Multiplies this object by the argument, returning this.selfSqr()
Squares this object.final DD
selfSubtract
(double y) Subtracts the argument from the value of this.final DD
selfSubtract
(DD y) Subtracts the argument from the value of this.setValue
(double value) Set the value for the DD object.Set the value for the DD object.int
signum()
Returns an integer indicating the sign of this value.sqr()
Computes the square of this value.static DD
sqr
(double x) Computes the square of this value.sqrt()
Computes the positive square root of this value.static DD
sqrt
(double x) final DD
subtract
(double y) Computes a new DoubleDouble object whose value is (this - y).final DD
Computes a new DoubleDouble object whose value is (this - y).Returns the string representation of this value in scientific notation.Returns the string representation of this value in standard notation.toString()
Returns a string representation of this number, in either standard or scientific notation.trunc()
Returns the integer which is largest in absolute value and not further from zero than this value.static DD
valueOf
(double x) Converts the double argument to a DoubleDouble number.static DD
Converts the string argument to a DoubleDouble number.
-
Field Details
-
PI
The value nearest to the constant Pi. -
TWO_PI
The value nearest to the constant 2 * Pi. -
PI_2
The value nearest to the constant Pi / 2. -
E
The value nearest to the constant e (the natural logarithm base). -
NaN
A value representing the result of an operation which does not return a valid number. -
EPS
public static final double EPSThe smallest representable relative difference between two {link @ DoubleDouble} values- See Also:
-
-
Constructor Details
-
DD
public DD()Creates a new DoubleDouble with value 0.0. -
DD
public DD(double x) Creates a new DoubleDouble with value x.- Parameters:
x
- the value to initialize
-
DD
public DD(double hi, double lo) Creates a new DoubleDouble with value (hi, lo).- Parameters:
hi
- the high-order componentlo
- the high-order component
-
DD
Creates a new DoubleDouble with value equal to the argument.- Parameters:
dd
- the value to initialize
-
DD
Creates a new DoubleDouble with value equal to the argument.- Parameters:
str
- the value to initialize by- Throws:
NumberFormatException
- if str is not a valid representation of a number
-
-
Method Details
-
valueOf
Converts the string argument to a DoubleDouble number.- Parameters:
str
- a string containing a representation of a numeric value- Returns:
- the extended precision version of the value
- Throws:
NumberFormatException
- if s is not a valid representation of a number
-
valueOf
Converts the double argument to a DoubleDouble number.- Parameters:
x
- a numeric value- Returns:
- the extended precision version of the value
-
copy
Creates a new DoubleDouble with the value of the argument.- Parameters:
dd
- the DoubleDouble value to copy- Returns:
- a copy of the input value
-
clone
Creates and returns a copy of this value.- Returns:
- a copy of this value
-
setValue
Set the value for the DD object. This method supports the mutating operations concept described in the class documentation (see above).- Parameters:
value
- a DD instance supplying an extended-precision value.- Returns:
- a self-reference to the DD instance.
-
setValue
Set the value for the DD object. This method supports the mutating operations concept described in the class documentation (see above).- Parameters:
value
- a floating point value to be stored in the instance.- Returns:
- a self-reference to the DD instance.
-
add
Returns a new DoubleDouble whose value is (this + y).- Parameters:
y
- the addend- Returns:
- (this + y)
-
add
Returns a new DoubleDouble whose value is (this + y).- Parameters:
y
- the addend- Returns:
- (this + y)
-
selfAdd
Adds the argument to the value of this. To prevent altering constants, this method must only be used on values known to be newly created.- Parameters:
y
- the addend- Returns:
- this object, increased by y
-
selfAdd
Adds the argument to the value of this. To prevent altering constants, this method must only be used on values known to be newly created.- Parameters:
y
- the addend- Returns:
- this object, increased by y
-
subtract
Computes a new DoubleDouble object whose value is (this - y).- Parameters:
y
- the subtrahend- Returns:
- (this - y)
-
subtract
Computes a new DoubleDouble object whose value is (this - y).- Parameters:
y
- the subtrahend- Returns:
- (this - y)
-
selfSubtract
Subtracts the argument from the value of this. To prevent altering constants, this method must only be used on values known to be newly created.- Parameters:
y
- the addend- Returns:
- this object, decreased by y
-
selfSubtract
Subtracts the argument from the value of this. To prevent altering constants, this method must only be used on values known to be newly created.- Parameters:
y
- the addend- Returns:
- this object, decreased by y
-
negate
Returns a new DoubleDouble whose value is -this.- Returns:
- -this
-
multiply
Returns a new DoubleDouble whose value is (this * y).- Parameters:
y
- the multiplicand- Returns:
- (this * y)
-
multiply
Returns a new DoubleDouble whose value is (this * y).- Parameters:
y
- the multiplicand- Returns:
- (this * y)
-
selfMultiply
Multiplies this object by the argument, returning this. To prevent altering constants, this method must only be used on values known to be newly created.- Parameters:
y
- the value to multiply by- Returns:
- this object, multiplied by y
-
selfMultiply
Multiplies this object by the argument, returning this. To prevent altering constants, this method must only be used on values known to be newly created.- Parameters:
y
- the value to multiply by- Returns:
- this object, multiplied by y
-
divide
Computes a new DoubleDouble whose value is (this / y).- Parameters:
y
- the divisor- Returns:
- a new object with the value (this / y)
-
divide
Computes a new DoubleDouble whose value is (this / y).- Parameters:
y
- the divisor- Returns:
- a new object with the value (this / y)
-
selfDivide
Divides this object by the argument, returning this. To prevent altering constants, this method must only be used on values known to be newly created.- Parameters:
y
- the value to divide by- Returns:
- this object, divided by y
-
selfDivide
Divides this object by the argument, returning this. To prevent altering constants, this method must only be used on values known to be newly created.- Parameters:
y
- the value to divide by- Returns:
- this object, divided by y
-
reciprocal
Returns a DoubleDouble whose value is 1 / this.- Returns:
- the reciprocal of this value
-
floor
Returns the largest (closest to positive infinity) value that is not greater than the argument and is equal to a mathematical integer. Special cases:- If this value is NaN, returns NaN.
- Returns:
- the largest (closest to positive infinity) value that is not greater than the argument and is equal to a mathematical integer.
-
ceil
Returns the smallest (closest to negative infinity) value that is not less than the argument and is equal to a mathematical integer. Special cases:- If this value is NaN, returns NaN.
- Returns:
- the smallest (closest to negative infinity) value that is not less than the argument and is equal to a mathematical integer.
-
signum
public int signum()Returns an integer indicating the sign of this value.- if this value is > 0, returns 1
- if this value is < 0, returns -1
- if this value is = 0, returns 0
- if this value is NaN, returns 0
- Returns:
- an integer indicating the sign of this value
-
rint
Rounds this value to the nearest integer. The value is rounded to an integer by adding 1/2 and taking the floor of the result. Special cases:- If this value is NaN, returns NaN.
- Returns:
- this value rounded to the nearest integer
-
trunc
Returns the integer which is largest in absolute value and not further from zero than this value. Special cases:- If this value is NaN, returns NaN.
- Returns:
- the integer which is largest in absolute value and not further from zero than this value
-
abs
Returns the absolute value of this value. Special cases:- If this value is NaN, it is returned.
- Returns:
- the absolute value of this value
-
sqr
Computes the square of this value.- Returns:
- the square of this value.
-
selfSqr
Squares this object. To prevent altering constants, this method must only be used on values known to be newly created.- Returns:
- the square of this value.
-
sqr
Computes the square of this value.- Returns:
- the square of this value.
-
sqrt
Computes the positive square root of this value. If the number is NaN or negative, NaN is returned.- Returns:
- the positive square root of this number. If the argument is NaN or less than zero, the result is NaN.
-
sqrt
-
pow
Computes the value of this number raised to an integral power. Follows semantics of Java Math.pow as closely as possible.- Parameters:
exp
- the integer exponent- Returns:
- x raised to the integral power exp
-
determinant
Computes the determinant of the 2x2 matrix with the given entries.- Parameters:
x1
- a double valuey1
- a double valuex2
- a double valuey2
- a double value- Returns:
- the determinant of the values
-
determinant
Computes the determinant of the 2x2 matrix with the given entries.- Parameters:
x1
- a matrix entryy1
- a matrix entryx2
- a matrix entryy2
- a matrix entry- Returns:
- the determinant of the matrix of values
-
min
Computes the minimum of this and another DD number.- Parameters:
x
- a DD number- Returns:
- the minimum of the two numbers
-
max
Computes the maximum of this and another DD number.- Parameters:
x
- a DD number- Returns:
- the maximum of the two numbers
-
doubleValue
public double doubleValue()Converts this value to the nearest double-precision number.- Returns:
- the nearest double-precision number to this value
-
intValue
public int intValue()Converts this value to the nearest integer.- Returns:
- the nearest integer to this value
-
isZero
public boolean isZero()Tests whether this value is equal to 0.- Returns:
- true if this value is equal to 0
-
isNegative
public boolean isNegative()Tests whether this value is less than 0.- Returns:
- true if this value is less than 0
-
isPositive
public boolean isPositive()Tests whether this value is greater than 0.- Returns:
- true if this value is greater than 0
-
isNaN
public boolean isNaN()Tests whether this value is NaN.- Returns:
- true if this value is NaN
-
equals
Tests whether this value is equal to another DoubleDouble value.- Parameters:
y
- a DoubleDouble value- Returns:
- true if this value = y
-
gt
Tests whether this value is greater than another DoubleDouble value.- Parameters:
y
- a DoubleDouble value- Returns:
- true if this value > y
-
ge
Tests whether this value is greater than or equals to another DoubleDouble value.- Parameters:
y
- a DoubleDouble value- Returns:
- true if this value >= y
-
lt
Tests whether this value is less than another DoubleDouble value.- Parameters:
y
- a DoubleDouble value- Returns:
- true if this value < y
-
le
Tests whether this value is less than or equal to another DoubleDouble value.- Parameters:
y
- a DoubleDouble value- Returns:
- true if this value <= y
-
compareTo
Compares two DoubleDouble objects numerically.- Specified by:
compareTo
in interfaceComparable
- Returns:
- -1,0 or 1 depending on whether this value is less than, equal to or greater than the value of o
-
dump
Dumps the components of this number to a string.- Returns:
- a string showing the components of the number
-
toString
Returns a string representation of this number, in either standard or scientific notation. If the magnitude of the number is in the range [ 10-3, 108 ] standard notation will be used. Otherwise, scientific notation will be used. -
toStandardNotation
Returns the string representation of this value in standard notation.- Returns:
- the string representation in standard notation
-
toSciNotation
Returns the string representation of this value in scientific notation.- Returns:
- the string representation in scientific notation
-
parse
Converts a string representation of a real number into a DoubleDouble value. The format accepted is similar to the standard Java real number syntax. It is defined by the following regular expression:[+|-] {digit} [ . {digit} ] [ ( e | E ) [+|-] {digit}+
- Parameters:
str
- the string to parse- Returns:
- the value of the parsed number
- Throws:
NumberFormatException
- if str is not a valid representation of a number
-