com.sgi.math
Class CR

java.lang.Object
  |
  +--java.lang.Number
        |
        +--com.sgi.math.CR

All Implemented Interfaces:

java.io.Serializable

public abstract class CR

extends java.lang.Number

Constructive real numbers, also known as recursive, or computable reals. Each recursive real number is represented as an object that provides an approximation function for the real number. The approximation function guarantees that the generated approximation is accurate to the specified precision. Arithmetic operations on constructive reals produce new such objects; they typically do not perform any real computation. In this sense, arithmetic computations are exact: They produce a description which describes the exact answer, and can be used to later approximate it to arbitrary precision.

When approximations are generated, e.g. for output, they are accurate to the requested precision; no cumulative rounding errors are visible. In order to achieve this precision, the approximation function will often need to approximate subexpressions to greater precision than was originally demanded. Thus the approximation of a constructive real number generated through a complex sequence of operations may eventually require evaluation to very high precision. This usually makes such computations prohibitively expensive for large numerical problems. But it is perfectly appropriate for use in a desk calculator, for small numerical problems, for the evaluation of expressions computated by a symbolic algebra system, for testing of accuracy claims for floating point code on small inputs, or the like.

We expect that the vast majority of uses will ignore the particular implementation, and the member functons approximate and get_appr. Such applications will treat CR as a conventional numerical type, with an interface modelled on java.math.BigInteger. No subclasses of CR will be explicitly mentioned by such a program.

All standard arithmetic operations, as well as a few algebraic and transcendal functions are provided. Constructive reals are immutable; thus all of these operations return a new constructive real.

A few uses will require explicit construction of approximation functions. The requires the construction of a subclass of CR with an overridden approximate function. Note that approximate should only be defined, but never called. get_appr provides the same functionality, but adds the caching necessary to obtain reasonable performance.

Any operation may throw com.sgi.math.AbortedError if the thread in which it is executing is interrupted. (InterruptedException cannot be used for this purpose, since CR inherits from Number.)

Any operation may also throw com.sgi.math.PrecisionOverflowError If the precision request generated during any subcalculation overflows a 28-bit integer. (This should be extremely unlikely, except as an outcome of a division by zero, or other erroneous computation.)

See Also:

Serialized Form

Field Summary

static CR	PI The ratio of a circle's circumference to its diameter.
static boolean	please_stop Setting this to true requests that all computations be aborted by throwing AbortedError.

Constructor Summary

CR()

Method Summary

CR	abs() The absolute value of a constructive reals.
CR	add(CR x) Add two constructive reals.
protected abstract java.math.BigInteger	approximate(int precision) Must be defined in subclasses of CR.
java.math.BigInteger	BigIntegerValue() Return a BigInteger which differs by less than one from the constructive real.
int	compareTo(CR x) Should be called only if x != y.
int	compareTo(CR x, int a) Approximate comparison with only an absolute tolerance.
int	compareTo(CR x, int r, int a) Return 0 if x = y to within the indicated tolerance, -1 if x < y, and +1 if x > y.
CR	cos() The trigonometric cosine function.
CR	divide(CR x) The quotient of two constructive reals.
double	doubleValue() Return a double which differs by less than one in the least represented bit from the constructive real.
CR	exp() The exponential function, i.e.
float	floatValue() Return a float which differs by less than one in the least represented bit from the constructive real.
java.math.BigInteger	get_appr(int precision) Returns value / 2 ** prec rounded to an integer.
int	intValue() Return an int which differs by less than one from the constructive real.
CR	inverse() The multiplicative inverse of a constructive real.
CR	ln() The natural (base e) logarithm.
long	longValue() Return a long which differs by less than one from the constructive real.
CR	max(CR x) The maximum of two constructive reals.
CR	min(CR x) The minimum of two constructive reals.
CR	multiply(CR x) The product of two constructive reals
CR	negate() The additive inverse of a constructive real
CR	select(CR x, CR y) The real number x if this < 0, or y otherwise.
CR	shiftLeft(int n) Multiply a constructive real by 2**n.
CR	shiftRight(int n) Multiply a constructive real by 2**(-n).
int	signum() Should be called only if x != 0.
int	signum(int a) Equivalent to compareTo(CR.valueOf(0), a)
CR	sin() The trigonometric sine function.
CR	sqrt() The square root of a constructive real.
CR	subtract(CR x) The difference between two constructive reals
java.lang.String	toString() Equivalent to toString(10, 10)
java.lang.String	toString(int n) Equivalent to toString(n,10)
java.lang.String	toString(int n, int radix) Return a textual representation accurate to n places to the right of the decimal point.
static CR	valueOf(java.math.BigInteger n) The constructive real number corresponding to a BigInteger.
static CR	valueOf(double n) The constructive real number corresponding to a Java double.
static CR	valueOf(float n) The constructive real number corresponding to a Java float.
static CR	valueOf(int n) The constructive real number corresponding to a Java int.
static CR	valueOf(long n) The constructive real number corresponding to a Java long.
static CR	valueOf(java.lang.String s, int radix) Return the constructive real number corresponding to the given textual representation and radix.

Methods inherited from class java.lang.Number

byteValue, shortValue

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

please_stop

public static volatile boolean please_stop

Setting this to true requests that all computations be aborted by throwing AbortedError. Must be rest to false before any further computation. Ideally Thread.interrupt() should be used instead, but that doesn't appear to be consistently supported by browser VMs.

PI

public static CR PI

The ratio of a circle's circumference to its diameter.

Constructor Detail

CR

public CR()

Method Detail

approximate

protected abstract java.math.BigInteger approximate(int precision)

Must be defined in subclasses of CR. Most users can ignore the existence of this method, and will not ever need to define a CR subclass. Returns value / base ** prec rounded to an integer. The error in the result is strictly < 1. Informally, approximate(n) gives a scaled approximation accurate to 2**n. Implementations may safely assume that precision is at least a factor of 8 away from overflow.

valueOf

public static CR valueOf(java.math.BigInteger n)

The constructive real number corresponding to a BigInteger.

valueOf

public static CR valueOf(int n)

The constructive real number corresponding to a Java int.

valueOf

public static CR valueOf(long n)

The constructive real number corresponding to a Java long.

valueOf

public static CR valueOf(double n)

The constructive real number corresponding to a Java double. The result is undefined if argument is infinite or NaN.

valueOf

public static CR valueOf(float n)

The constructive real number corresponding to a Java float. The result is undefined if argument is infinite or NaN.

get_appr

public java.math.BigInteger get_appr(int precision)

Returns value / 2 ** prec rounded to an integer. The error in the result is strictly < 1. Produces the same answer as approximate, but uses and maintains a cached approximation. Normally not overridden, and called only from approximate methods in subclasses. Not needed if the provided operations on constructive reals suffice.

compareTo

public int compareTo(CR x,
                     int r,
                     int a)

Return 0 if x = y to within the indicated tolerance, -1 if x < y, and +1 if x > y. If x and y are indeed equal, it is guaranteed that 0 will be returned. If they differ by less than the tolerance, anything may happen. The tolerance allowed is the maximum of (abs(this)+abs(x))*(2**r) and 2**a

Parameters:

x - The other constructive real

r - Relative tolerance in bits

a - Absolute tolerance in bits

compareTo

public int compareTo(CR x,
                     int a)

Approximate comparison with only an absolute tolerance. Identical to the three argument version, but without a relative tolerance. Result is 0 if both constructive reals are equal, indeterminate if they differ by less than 2**a.

Parameters:

x - The other constructive real

a - Absolute tolerance in bits

compareTo

public int compareTo(CR x)

Should be called only if x != y. Return -1 if this < x, or +1 if this > x. If this == x, this will not terminate correctly; typically it will run until it exhausts memory. If the two constructive reals may be equal, the two or 3 argument version of compareTo should be used.

signum

public int signum(int a)

Equivalent to compareTo(CR.valueOf(0), a)

signum

public int signum()

Should be called only if x != 0. Return -1 if negative, +1 if positive. In the 0 case, this will not terminate correctly; typically it will run until it exhausts memory. If the two constructive reals may be equal, the one or two argument version of signum should be used.

valueOf

public static CR valueOf(java.lang.String s,
                         int radix)
                  throws java.lang.NumberFormatException

Return the constructive real number corresponding to the given textual representation and radix.

Parameters:

s - [-] digit* [. digit*]

radix -

toString

public java.lang.String toString(int n,
                                 int radix)

Return a textual representation accurate to n places to the right of the decimal point. n must be nonnegative.

Parameters:

n - Number of digits included to the right of decimal point

radix - Base ( >= 2, <= 16) for the resulting representation.

toString

public java.lang.String toString(int n)

Equivalent to toString(n,10)

Parameters:

n - Number of digits included to the right of decimal point

toString

public java.lang.String toString()

Equivalent to toString(10, 10)

Overrides:

toString in class java.lang.Object

BigIntegerValue

public java.math.BigInteger BigIntegerValue()

Return a BigInteger which differs by less than one from the constructive real.

intValue

public int intValue()

Return an int which differs by less than one from the constructive real. Behavior on overflow is undefined.

Overrides:

intValue in class java.lang.Number

longValue

public long longValue()

Return a long which differs by less than one from the constructive real. Behavior on overflow is undefined.

Overrides:

longValue in class java.lang.Number

doubleValue

public double doubleValue()

Return a double which differs by less than one in the least represented bit from the constructive real.

Overrides:

doubleValue in class java.lang.Number

floatValue

public float floatValue()

Return a float which differs by less than one in the least represented bit from the constructive real.

Overrides:

floatValue in class java.lang.Number

add

public CR add(CR x)

Add two constructive reals.

shiftLeft

public CR shiftLeft(int n)

Multiply a constructive real by 2**n.

Parameters:

n - shift count, may be negative

shiftRight

public CR shiftRight(int n)

Multiply a constructive real by 2**(-n).

Parameters:

n - shift count, may be negative

negate

public CR negate()

The additive inverse of a constructive real

subtract

public CR subtract(CR x)

The difference between two constructive reals

multiply

public CR multiply(CR x)

The product of two constructive reals

inverse

public CR inverse()

The multiplicative inverse of a constructive real. x.inverse() is equivalent to CR.valueOf(1).divide(x).

divide

public CR divide(CR x)

The quotient of two constructive reals.

select

public CR select(CR x,
                 CR y)

The real number x if this < 0, or y otherwise. Requires x = y if this = 0. Since comparisons may diverge, this is often a useful alternative to conditionals.

max

public CR max(CR x)

The maximum of two constructive reals.

min

public CR min(CR x)

The minimum of two constructive reals.

abs

public CR abs()

The absolute value of a constructive reals. Note that this cannot be written as a conditional.

exp

public CR exp()

The exponential function, i.e. e**this.

cos

public CR cos()

The trigonometric cosine function.

sin

public CR sin()

The trigonometric sine function.

ln

public CR ln()

The natural (base e) logarithm.

sqrt

public CR sqrt()

The square root of a constructive real.