org.jscience.mathematics.numbers
Class Real

java.lang.Object
  javolution.context.RealtimeObject
      org.jscience.mathematics.numbers.Number<Real>
          org.jscience.mathematics.numbers.Real

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<Real>, Realtime, Immutable, Field<Real>, GroupAdditive<Real>, GroupMultiplicative<Real>, Ring<Real>, Structure<Real>

public final class Real
extends Number<Real>
implements Field<Real>

This class represents a real number of arbitrary precision with known/guaranteed uncertainty. A real number consists of a mantissa, a maximum error (on the mantissa) and a decimal exponent: ((mantissa ± error) · 10exponent).

Reals number can be exact (e.g. integer values scaled by a power of ten). Exactness is maintained for Ring operations (e.g. addition, multiplication), but typically lost when a multiplicative inverse() is calculated. The minimum precision for an exact number is set by setExactMinimumPrecision(int) (context local setting, default 19 digits).

The actual precision and accuracy of any real number is available and guaranteed (the true/exact value is always within the precision/accuracy range).

Operations on instances of this class are quite fast as information substantially below the precision level (aka noise) is not processed/stored. There is no limit on a real precision but precision degenerates (due to numeric errors) and calculations accelerate as more and more operations are performed.

Instances of this class can be utilized to find approximate solutions to linear equations using the Matrix class for which high-precision reals is often required, the primitive type double being not accurate enough to resolve equations when the matrix's size exceeds 100x100. Furthermore, even for small matrices the "qualified" result is indicative of possible system singularities.

Version:

3.3, January 8, 2006

Author:

Jean-Marie Dautelle

See Also:

Wikipedia: Real number, Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class javolution.context.RealtimeObject

RealtimeObject.Factory<T extends RealtimeObject>

Nested classes/interfaces inherited from interface javolution.context.Realtime

Realtime.ObjectSpace

Field Summary

static Real	NaN Holds a Not-a-Number instance (infinite error).
static Real	ONE Holds the exact ONE instance.
protected static XMLFormat<Real>	XML Holds the default XML representation for real numbers.
static Real	ZERO Holds the exact ZERO instance.

Method Summary

Real	abs() Returns the absolute value of this real number.
boolean	approximates(Real that) Indicates if this real approximates the one specified.
int	compareTo(Real that) Compares two real numbers numerically.
Real	divide(long divisor) Returns this real number divided by the specified int divisor.
Real	divide(Real that) Returns this real number divided by the one specified.
double	doubleValue() Returns the value of this real number as a double.
boolean	equals(java.lang.Object that) Compares this real number against the specified object.
int	getAccuracy() Returns the number of decimal digits guaranteed exact which appear to the right of the decimal point (absolute error).
LargeInteger	getError() Returns the maximum error (positive) on this real mantissa.
static int	getExactMinimumPrecision() Returns the local minimum precision when exact numbers have to be approximated.
int	getExponent() Returns the exponent of the power of 10 multiplier.
LargeInteger	getMantissa() Returns this real mantissa.
int	getPrecision() Returns the total number of decimal digits guaranteed exact (relative error).
int	hashCode() Returns the hash code for this real number.
Real	inverse() Returns the reciprocal (or inverse) of this real number.
boolean	isExact() Indicates if this real number is exact (error == 0).
boolean	isLargerThan(Real that) Compares the absolute value of two real numbers.
boolean	isNaN() Indicates if this real is Not-a-Number (unbounded value interval).
boolean	isNegative() Indicates if this real is less than zero.
boolean	isPositive() Indicates if this real is greater than zero.
long	longValue() Returns the value of this real number as a long.
Real	minus(Real that) Returns the difference between this real number and the one specified.
boolean	move(Realtime.ObjectSpace os) Moves this real-time object to the specified object space.
Real	opposite() Returns the negation of this real number.
Real	plus(Real that) Returns the sum of this real number with the one specified.
static void	setExactMinimumPrecision(int precision) Sets the local minimum precision when exact numbers have to be approximated.
Real	sqrt() Returns the square root of this real number, the more accurate is this real number, the more accurate the square root.
Real	times(long multiplier) Returns the product of this real number with the specified long multiplier.
Real	times(Real that) Returns the product of this real number with the one specified.
LargeInteger	toLargeInteger() Converts this real to a LargeInteger instance.
Text	toText() Returns the decimal text representation of this number.
static Real	valueOf(java.lang.CharSequence chars) Returns the real for the specified character sequence.
static Real	valueOf(double doubleValue) Returns the real number (inexact except for 0.0) corresponding to the specified double value.
static Real	valueOf(LargeInteger mantissa, LargeInteger error, int exponent) Returns a real having the specified mantissa, error and exponent values.
static Real	valueOf(long longValue) Returns the exact real number corresponding to the specified long value (convenience method).

Methods inherited from class org.jscience.mathematics.numbers.Number

byteValue, floatValue, intValue, isGreaterThan, isLessThan, pow, shortValue

Methods inherited from class javolution.context.RealtimeObject

export, isLocal, moveHeap, preserve, toString, unpreserve

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

XML

protected static final XMLFormat<Real> XML

Holds the default XML representation for real numbers. This representation consists of a simple value attribute holding the textual representation.

NaN

public static final Real NaN

Holds a Not-a-Number instance (infinite error).

ZERO

public static final Real ZERO

Holds the exact ZERO instance.

ONE

public static final Real ONE

Holds the exact ONE instance.

Method Detail

getExactMinimumPrecision

public static int getExactMinimumPrecision()

Returns the local minimum precision when exact numbers have to be approximated.

Returns:

the minimum number of digits assumed exact for exact real numbers.

setExactMinimumPrecision

public static void setExactMinimumPrecision(int precision)

Sets the local minimum precision when exact numbers have to be approximated.

Parameters:

precision - the minimum number of digits assumed exact for exact numbers.

valueOf

public static Real valueOf(LargeInteger mantissa,
                           LargeInteger error,
                           int exponent)

Returns a real having the specified mantissa, error and exponent values. If the error is 0, the real is assumed exact. For example:

 
     // x = 0.0 ± 0.01 
     Real x = Real.valueOf(LargeInteger.ZERO, LargeInteger.ONE, -2);
                           
      // y = -12.3 exact 
     Real y = Real.valueOf(LargeInteger.valueOf("-123"), LargeInteger.ZERO, -1);
 
 

Parameters:

mantissa - this real mantissa.

error - the maximum error on the mantissa.

exponent - the decimal exponent.

Returns:

(mantissa ± error)·10exponent)

Throws:

java.lang.IllegalArgumentException - if error < 0

valueOf

public static Real valueOf(double doubleValue)

Returns the real number (inexact except for 0.0) corresponding to the specified double value. The error is derived from the inexact representation of double values intrinsic to the 64 bits IEEE 754 format.

Parameters:

doubleValue - the double value to convert.

Returns:

the corresponding real number.

valueOf

public static Real valueOf(long longValue)

Returns the exact real number corresponding to the specified long value (convenience method).

Parameters:

longValue - the exact long value.

Returns:

Real.valueOf(LargeInteger.valueOf(longValue), 0, 0)

valueOf

public static Real valueOf(java.lang.CharSequence chars)
                    throws java.lang.NumberFormatException

Returns the real for the specified character sequence. If the precision is not specified (using the ± symbol), the real is supposed exact. Example of valid character sequences:

"1.2E3" (1200 exact)

"1.2E3±1E-2" (1200 ± 0.01)

Parameters:

chars - the character sequence.

Returns:

the corresponding real number.

Throws:

java.lang.NumberFormatException - if the character sequence does not contain a parsable real.

getMantissa

public LargeInteger getMantissa()

Returns this real mantissa.

Returns:

the mantissa.

getError

public LargeInteger getError()

Returns the maximum error (positive) on this real mantissa.

Returns:

the maximum error on the mantissa.

getExponent

public int getExponent()

Returns the exponent of the power of 10 multiplier.

Returns:

the decimal exponent.

isExact

public boolean isExact()

Indicates if this real number is exact (error == 0).

Returns:

getError() == 0

getAccuracy

public int getAccuracy()

Returns the number of decimal digits guaranteed exact which appear to the right of the decimal point (absolute error).

Returns:

a measure of the absolute error of this real number.

getPrecision

public final int getPrecision()

Returns the total number of decimal digits guaranteed exact (relative error).

Returns:

a measure of the relative error of this real number.

isPositive

public boolean isPositive()

Indicates if this real is greater than zero.

Returns:

this > 0

isNegative

public boolean isNegative()

Indicates if this real is less than zero.

Returns:

this < 0

isNaN

public boolean isNaN()

Indicates if this real is Not-a-Number (unbounded value interval).

Returns:

true if this number has unbounded value interval; false otherwise.

approximates

public boolean approximates(Real that)

Indicates if this real approximates the one specified. This method takes into account possible errors (e.g. numeric errors) to make this determination.

Note: This method returns true if this or that isNaN() (basically Not-A-Number approximates anything).

Parameters:

that - the real to compare with.

Returns:

this ≈ that

toLargeInteger

public LargeInteger toLargeInteger()

Converts this real to a LargeInteger instance. Any fractional part of this real is discarded.

Returns:

the integer part of this real.

Throws:

java.lang.ArithmeticException - if this.isNaN()

opposite

public Real opposite()

Returns the negation of this real number.

Specified by:

opposite in interface GroupAdditive<Real>

Returns:

-this.

plus

public Real plus(Real that)

Returns the sum of this real number with the one specified.

Specified by:

plus in interface GroupAdditive<Real>

Parameters:

that - the real to be added.

Returns:

this + that.

minus

public Real minus(Real that)

Returns the difference between this real number and the one specified.

Overrides:

minus in class Number<Real>

Parameters:

that - the real to be subtracted.

Returns:

this - that.

times

public Real times(long multiplier)

Returns the product of this real number with the specified long multiplier.

Parameters:

multiplier - the long multiplier.

Returns:

this · multiplier.

times

public Real times(Real that)

Returns the product of this real number with the one specified.

Specified by:

times in interface GroupMultiplicative<Real>

Specified by:

times in interface Ring<Real>

Parameters:

that - the real multiplier.

Returns:

this · that.

divide

public Real divide(long divisor)

Returns this real number divided by the specified int divisor.

Parameters:

divisor - the int divisor.

Returns:

this / divisor

divide

public Real divide(Real that)

Returns this real number divided by the one specified.

Parameters:

that - the real divisor.

Returns:

this / that.

Throws:

java.lang.ArithmeticException - if that.equals(ZERO)

inverse

public Real inverse()

Returns the reciprocal (or inverse) of this real number.

Specified by:

inverse in interface GroupMultiplicative<Real>

Returns:

1 / this.

abs

public Real abs()

Returns the absolute value of this real number.

Returns:

|this|.

isLargerThan

public boolean isLargerThan(Real that)

Compares the absolute value of two real numbers.

Specified by:

isLargerThan in class Number<Real>

Parameters:

that - the real number to be compared with.

Returns:

|this| > |that|

sqrt

public Real sqrt()

Returns the square root of this real number, the more accurate is this real number, the more accurate the square root.

Returns:

the positive square root of this real number.

toText

public Text toText()

Returns the decimal text representation of this number.

Specified by:

toText in interface Realtime

Specified by:

toText in class Number<Real>

Returns:

the text representation of this number.

equals

public boolean equals(java.lang.Object that)

Compares this real number against the specified object.

Note: This method returns true if this or that is Not-A-Number, even though Double.NaN == Double.NaN has the value false.

Specified by:

equals in class Number<Real>

Parameters:

that - the object to compare with.

Returns:

true if the objects are two reals with same mantissa, error and exponent;false otherwise.

hashCode

public int hashCode()

Returns the hash code for this real number.

Specified by:

hashCode in class Number<Real>

Returns:

the hash code value.

longValue

public long longValue()

Returns the value of this real number as a long.

Specified by:

longValue in class Number<Real>

Returns:

the numeric value represented by this real after conversion to type long.

doubleValue

public double doubleValue()

Returns the value of this real number as a double.

Specified by:

doubleValue in class Number<Real>

Returns:

the numeric value represented by this real after conversion to type double.

compareTo

public int compareTo(Real that)

Compares two real numbers numerically.

Specified by:

compareTo in interface java.lang.Comparable<Real>

Specified by:

compareTo in class Number<Real>

Parameters:

that - the real to compare with.

Returns:

-1, 0 or 1 as this real is numerically less than, equal to, or greater than that.

Throws:

java.lang.ClassCastException - that is not a Real.

move

public boolean move(Realtime.ObjectSpace os)

Description copied from class: Number

Moves this real-time object to the specified object space.

Specified by:

move in interface Realtime

Overrides:

move in class Number<Real>

Parameters:

os - the object space to move this real-time object to.

Returns:

true if the move has to be propagated to external real-time references; false otherwise.