com.rubecula.jquantity
Class Approximation

java.lang.Object
  com.rubecula.util.Item
      com.rubecula.jquantity.BaseNumber
          com.rubecula.jquantity.Approximation

All Implemented Interfaces:

Arithmetical, Auditable, java.lang.Comparable, Divisible, Estimable, Fuzzy, Identifiable, Millable, Presentable, java.io.Serializable, Trigonometrical

public class Approximation

extends BaseNumber

implements Estimable, Trigonometrical, Divisible

This Class approximates a value using an immutable double-precision value. Note that this class is limited in its ability to store large numbers. For such numbers, or for numbers which are rational, Rational should be used. This Class should only be used for the results of applying arbitrary mathematical functions to numbers - such numbers are generally less precise than is possible with double precision in any case, so this class is normally adequate - provided that the size limit is not exceeded.

Since:

V_0_1

Version:

$Revision: 1.39 $ // TODO Add javadoc to many of the methods.

Author:

Robin Hillyard

See Also:

Serialized Form

Field Summary

private double	_Bound _Bound is the relative value of the estimate of the size of any error in the value itself (according to the model).
private int	_Model _Model is the distribution model of possible errors in the value itself.
private double	_Value The value of this approximation.
(package private) static Approximation	$_Alpha The fine structure constant, Alpha (dimensionless).
(package private) static Approximation	$_au Astronomical Unit (approx): 1.49597893*E11.
(package private) static Approximation	$_e Electron charge (in Coulombs) Value: 1.60217653(14)E-19.
(package private) static Approximation	$_G Gravitation constant (in m^3 kg^-1 sec^-2) Value: 6.6742(10) x 10-11 Relative Error: 1.5E-4.
(package private) static Approximation	$_R Rydberg constant (in per meters).
static Approximation	$1 The constant value of 1 (exact).
private static double	$1_Rt10 // TODO move this to end of file and check still OK
static Approximation	$e The constant value of e (best double-precision approximation).
static Approximation	$pi The constant value of pi (best double-precision approximation),
(package private) static int	$PrecisionDouble Number of significant figures held by doubles: 15 [pessimistic by half a place - 52 bits are used for mantissa]
(package private) static int	$PrecisionFloat Number of significant figures held by floats: 7 [pessimistic I think]
private static double	ERROR_ADD The relative error bounds for the double add operation.
private static double	ERROR_ATAN The relative error bounds for the arctan operation.
private static double	ERROR_DIV The relative error bounds for the double divide operation.
private static double	ERROR_EXP The relative error bounds for the exponential operation.
private static double	ERROR_LOG The relative error bounds for the natural logarithm operation.
private static double	ERROR_MUL The relative error bounds for the double multiply operation.
private static double	ERROR_TAN The relative error bounds for the tangent operation.

Fields inherited from class com.rubecula.jquantity.BaseNumber

Fields inherited from class com.rubecula.util.Item

JQUANTITY_TEST

Fields inherited from interface com.rubecula.jquantity.Fuzzy

$DistGaussian, $DistInvalid, $DistNone, $DistUniform, $Names

Constructor Summary

protected	Approximation() Constructor to create a new (exact) Approximation with value 0.
	Approximation(BaseNumber value) Primary constructor to create a new Approximation equivalent to a given BaseNumber.
	Approximation(double value) Primary constructor to create a new (exact) Approximation.
	Approximation(double value, double boundRel) Primary constructor to create a new Approximation.
	Approximation(double value, double boundRel, int model) Primary constructor to create a new Approximation.

Method Summary

Trigonometrical	arctanX2() Method to evaluate the arctangent function.
Trigonometrical	arctanX2(Approximation divisor) Method to evaluate the arctangent function of this divided by divisor.
java.lang.String	audit(java.lang.String label) Method to return a detailed string from an arithmetical object for debugging purposes.
double	doubleValue() Method to get the value of this approximation.
Trigonometrical	exp() Method to evaluate the exponential function.
Divisible	factored(double factor) Method to yield the quotient of this divided by factor, and return it as the result.
float	floatValue() Method to yield this value as a float.
double	getBound() Method to get the relative bound of this Rational.
double	getBoundAbs() Method to get the absolute bound of non-fuzzy value.
double	getEstimate() Method to get the current estimate of an arithmetical value.
java.lang.String	getIdentifier() Get an identifier for this object.
int	getModel() Method to get the error distribution model of this non-fuzzy object.
private static Approximation	InitialValueOf(java.lang.String string) Private class method to create an approximation from a string which represents a double, optionally followed by "*" to indicate fuzziness in the last digit.
(package private) static double	IntrinsicError() Method to get the intrinsic error of an ordinary double number.
(package private) static double	IntrinsicError(int halfplaces) Method to get the intrinsic error of a number accurate to 1/2 half-places significant figures.
int	intValue() If possible, get the integer value of this approximation.
Divisible	inverse() Method to yield the reciprocal of this and return it as the result.
boolean	isExact() Method to determine if the quantity represented is non-fuzzy;
boolean	isInfinite() Method to determine if this value is infinite.
boolean	isInteger() Method to determine if this object is an integer.
boolean	isUnity() Method to determine if this is equal to the value 1.
Trigonometrical	log() Method to evaluate the natural log function.
long	longValue() If possible, get the long value of this approximation.
static void	main(java.lang.String[] args) Test program.
Presentable	makePresentableInstance(Presentation presentation) Instance method to convert a Presentation into a Presentable.
protected BaseNumber	minus() Method to return this but with changed sign.
static Approximation	Parse(NumberPresentation presentation) Class method to translate the NumberPresentation representation into an Approximation.
protected BaseNumber	pow(double power) Method to yield the value of this to a power.
protected BaseNumber	pow(int power) Method to yield the value of this to a power.
Presentation	present(AttrMap attributes) Convert this Presentable object into a Presentation, according to the set of attributes provided.
protected BaseNumber	product(BaseNumber multiplicand) Method to yield the product of this approximation with a BaseNumber.
Divisible	quotient(BaseNumber divisor) Method to yield the quotient of this approximation divided by a BaseNumber.
(package private) static double	RootSumSquare(double x, double y) General method to yield the root-sum-square of two numbers, or in other words the length of the hyponteneuse of a right-angled triangle where x and y are the lengths of the two sides of the triange which include the right angle.
protected BaseNumber	scaled(long factor) Method to yield the result of scaling an approximation by a factor.
int	signum() Method to get the sign of this approximation.
protected BaseNumber	square() Method to yield the square of this value.
protected BaseNumber	sum(BaseNumber addend) Method to yield the sum of this approximation with a BaseNumber.
Trigonometrical	tan_theta_2() Method to evaluate the tangent function.
(package private) void	test(java.io.PrintStream output, java.lang.String name)
java.lang.String	toString() Method to represent this object as a string.
void	updateEstimate() No-op method to update the current estimate.
static BaseNumber	valueOf(java.lang.String valueString) Method to create an approximation from a string which represents a double, optionally followed by "*" to indicate fuzziness in the last digit.

Methods inherited from class com.rubecula.jquantity.BaseNumber

abs, bestModel, BestModel, byteValue, characteristic, Characteristic, difference, impartFuzziness, isEqual, isUncertain, isZero, shortValue, valueOf, valueOfLog10

Methods inherited from class com.rubecula.util.Item

audit, audit, compareTo, Debug, getClassNameShort, getType, IsDebug, present, SetDebug, test, test, Wrap

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.rubecula.util.Auditable

audit, audit

Field Detail

$1

public static final Approximation $1

The constant value of 1 (exact).

$pi

public static final Approximation $pi

The constant value of pi (best double-precision approximation),

See Also:

Math.PI

$e

public static final Approximation $e

The constant value of e (best double-precision approximation).

See Also:

Math.E

$_R

static final Approximation $_R

Rydberg constant (in per meters). Value: 10973731.568525(73) Relative Error: 6.6E-12. See Rinfinity.

$_Alpha

static final Approximation $_Alpha

The fine structure constant, Alpha (dimensionless). Value: 0.007297352568(24) Relative Error: 3.3E-9. See alpha.

$_e

static final Approximation $_e

Electron charge (in Coulombs) Value: 1.60217653(14)E-19. Relative Error: 8.5E-8. See e.

$_G

static final Approximation $_G

Gravitation constant (in m^3 kg^-1 sec^-2) Value: 6.6742(10) x 10-11 Relative Error: 1.5E-4. See G.

$_au

static final Approximation $_au

Astronomical Unit (approx): 1.49597893*E11.

$PrecisionDouble

static final int $PrecisionDouble

Number of significant figures held by doubles: 15 [pessimistic by half a place - 52 bits are used for mantissa]

See Also:

Constant Field Values

$PrecisionFloat

static final int $PrecisionFloat

Number of significant figures held by floats: 7 [pessimistic I think]

See Also:

Constant Field Values

$1_Rt10

private static final double $1_Rt10

// TODO move this to end of file and check still OK

_Value

private final double _Value

The value of this approximation.

_Bound

private final double _Bound

_Bound is the relative value of the estimate of the size of any error in the value itself (according to the model).

_Model

private final int _Model

_Model is the distribution model of possible errors in the value itself. The size of the errors is controlled by _Bound.

ERROR_ADD

private static final double ERROR_ADD

The relative error bounds for the double add operation. Current value is a guess: 1e-14.

See Also:

Constant Field Values

ERROR_MUL

private static final double ERROR_MUL

The relative error bounds for the double multiply operation. Current value is a guess: 2e-14.

See Also:

Constant Field Values

ERROR_DIV

private static final double ERROR_DIV

The relative error bounds for the double divide operation. Current value is a guess: 5e-14.

See Also:

Constant Field Values

ERROR_EXP

private static final double ERROR_EXP

The relative error bounds for the exponential operation. Current value is a guess: 1e-13.

See Also:

Constant Field Values

ERROR_LOG

private static final double ERROR_LOG

The relative error bounds for the natural logarithm operation. Current value is a guess: 1e-13.

See Also:

Constant Field Values

ERROR_TAN

private static final double ERROR_TAN

The relative error bounds for the tangent operation. Current value is a guess: 1e-13.

See Also:

Constant Field Values

ERROR_ATAN

private static final double ERROR_ATAN

The relative error bounds for the arctan operation. Current value is a guess: 1e-13.

See Also:

Constant Field Values

Constructor Detail

Approximation

public Approximation(double value,
                     double boundRel,
                     int model)

Primary constructor to create a new Approximation.

Parameters:

value - the closest known value to the quantity to be represented.

boundRel - the relative error bound on the value.

model - the error distribution model.

Approximation

public Approximation(double value,
                     double boundRel)

Primary constructor to create a new Approximation.

Parameters:

value - the closest known value to the quantity to be represented.

boundRel - the relative error bound on the value.

Approximation

public Approximation(double value)

Primary constructor to create a new (exact) Approximation.

Parameters:

value - the closest known value to the quantity to be represented.

Approximation

public Approximation(BaseNumber value)

Primary constructor to create a new Approximation equivalent to a given BaseNumber.

Parameters:

value - the equivalent Approximation to value.

Approximation

protected Approximation()

Constructor to create a new (exact) Approximation with value 0. This constructor is used in conjunction with the makePresentableInstance() method.

Method Detail

valueOf

public static BaseNumber valueOf(java.lang.String valueString)
                          throws PresentationException

Method to create an approximation from a string which represents a double, optionally followed by "*" to indicate fuzziness in the last digit.

Parameters:

valueString - The string representation of a double, optionally followed by "*".

Returns:

an Approximation with the appropriate error bound and value.

Throws:

PresentationException - problem parsing valueString.

InitialValueOf

private static Approximation InitialValueOf(java.lang.String string)

Private class method to create an approximation from a string which represents a double, optionally followed by "*" to indicate fuzziness in the last digit. This method returns the result from valueOf(String), printing any exception thrown on System.err. It is used for class initializations of values.

Parameters:

string - The string representation of a double, optionally followed by "*".

Returns:

an Approximation with the appropriate error bound and value (or null if an exception was thrown).

Parse

public static Approximation Parse(NumberPresentation presentation)
                           throws PresentationException

Class method to translate the NumberPresentation representation into an Approximation. Currently, numbers must be decimal (i.e. in base 10).

Parameters:

presentation - NumberPresentation representation of an approximation.

Returns:

a new instance of Approximation parsed from presentation.

Throws:

PresentationException - if presentation cannot be parsed as an Approximation.

updateEstimate

public void updateEstimate()

No-op method to update the current estimate. This method does nothing at all.

Specified by:

updateEstimate in interface Estimable

getEstimate

public double getEstimate()

Method to get the current estimate of an arithmetical value.

Specified by:

getEstimate in interface Estimable

Returns:

double: the current estimate.

inverse

public Divisible inverse()

Method to yield the reciprocal of this and return it as the result.
NOTE: it is a requirement of this method that the class of the result is the same as the class of this so that the result can be safely cast to the original class.

Specified by:

inverse in interface Divisible

Returns:

the reciprocal of this.

quotient

public Divisible quotient(BaseNumber divisor)

Method to yield the quotient of this approximation divided by a BaseNumber.

Specified by:

quotient in interface Divisible

Parameters:

divisor - the number to divide into this.

Returns:

this / divisor.

Throws:

java.lang.RuntimeException - if the divisor is zero.

factored

public Divisible factored(double factor)

Method to yield the quotient of this divided by factor, and return it as the result.
NOTE: it is a requirement of this method that the class of the result is the same as the class of this so that the result can be safely cast to the original class.

Specified by:

factored in interface Divisible

Parameters:

factor - the scale factor.

Returns:

the quotient of this divided by factor.

getBoundAbs

public double getBoundAbs()

Method to get the absolute bound of non-fuzzy value.

Overrides:

getBoundAbs in class BaseNumber

Returns:

the absolute bound of this.

See Also:

BaseNumber.getBound(), BaseNumber.doubleValue(), Math.abs(double)

getBound

public double getBound()

Method to get the relative bound of this Rational.

Specified by:

getBound in interface Fuzzy

Overrides:

getBound in class BaseNumber

Returns:

the relative bound.

getModel

public int getModel()

Method to get the error distribution model of this non-fuzzy object.

Specified by:

getModel in interface Fuzzy

Overrides:

getModel in class BaseNumber

Returns:

Fuzzy.$DistNone int: non-fuzzy distribution.

isExact

public boolean isExact()

Method to determine if the quantity represented is non-fuzzy;

Specified by:

isExact in interface Fuzzy

Overrides:

isExact in class BaseNumber

Returns:

true boolean: always

isInteger

public boolean isInteger()

Method to determine if this object is an integer.

Specified by:

isInteger in interface Arithmetical

Returns:

false.

scaled

protected BaseNumber scaled(long factor)

Method to yield the result of scaling an approximation by a factor.

Specified by:

scaled in class BaseNumber

Parameters:

factor - a long integer which is to be multiplied by this.

Returns:

this * factor.

product

protected BaseNumber product(BaseNumber multiplicand)

Method to yield the product of this approximation with a BaseNumber.

Specified by:

product in class BaseNumber

Parameters:

multiplicand - the number to multiply into this.

Returns:

this * multiplicand.

getIdentifier

public java.lang.String getIdentifier()

Get an identifier for this object.

Specified by:

getIdentifier in interface Identifiable

Returns:

the value as a string followed by "A".

intValue

public int intValue()

If possible, get the integer value of this approximation. Equal to longValue().

Specified by:

intValue in class BaseNumber

Returns:

tne equivalent integer which fits in an int.

Throws:

java.lang.RuntimeException - the integer is out of range.

java.lang.RuntimeException - this is not equivalent to an long (i.e. not integral).

longValue

public long longValue()

If possible, get the long value of this approximation.

Specified by:

longValue in class BaseNumber

Returns:

tne equivalent long which fits in an long.

Throws:

java.lang.RuntimeException - this is not equivalent to an long (i.e. not integral).

sum

protected BaseNumber sum(BaseNumber addend)

Method to yield the sum of this approximation with a BaseNumber.

Specified by:

sum in class BaseNumber

Parameters:

addend - the number to add to this.

Returns:

this * addend.

signum

public int signum()

Method to get the sign of this approximation.

Specified by:

signum in interface Arithmetical

Returns:

if zero then 0 else if positive then 1 else -1.

doubleValue

public double doubleValue()

Method to get the value of this approximation.

Specified by:

doubleValue in class BaseNumber

Returns:

the value.

isInfinite

public boolean isInfinite()

Method to determine if this value is infinite.

Specified by:

isInfinite in interface Arithmetical

Returns:

true if this is infinite.

audit

public java.lang.String audit(java.lang.String label)

Method to return a detailed string from an arithmetical object for debugging purposes.

Specified by:

audit in interface Auditable

Parameters:

label - String: the label to associate with the data.

Returns:

the detailed string.

isUnity

public boolean isUnity()

Method to determine if this is equal to the value 1.

Specified by:

isUnity in interface Arithmetical

Returns:

true if this is 1.

present

public Presentation present(AttrMap attributes)
                     throws PresentationException

Description copied from interface: Presentable

Convert this Presentable object into a Presentation, according to the set of attributes provided.

Specified by:

present in interface Presentable

Parameters:

attributes - the map of attributes required for the resulting presentation.

Returns:

an appropriate presentation of this quantity.

Throws:

PresentationException - if unable to parse appropriately.

exp

public Trigonometrical exp()

Method to evaluate the exponential function. This method is the inverse of log().

Specified by:

exp in interface Trigonometrical

Returns:

e(this) in the form of a Approximation.

log

public Trigonometrical log()

Method to evaluate the natural log function. This method is the inverse of exp().

Specified by:

log in interface Trigonometrical

Returns:

log(this) in the form of an Approximation.

Throws:

java.lang.RuntimeException - if this is not positive.

arctanX2

public Trigonometrical arctanX2(Approximation divisor)

Method to evaluate the arctangent function of this divided by divisor. This method is the inverse of tan_theta_2().

Parameters:

divisor - the divisor of the value from which to take twice the arctangent.

Returns:

2 * atan2(this,divisor) in the form of a Approximation.

arctanX2

public Trigonometrical arctanX2()

Method to evaluate the arctangent function. This method is the inverse of tan_theta_2().

Specified by:

arctanX2 in interface Trigonometrical

Returns:

arctanX2(1)).

tan_theta_2

public Trigonometrical tan_theta_2()

Method to evaluate the tangent function. This method is the inverse of arctanX2().

Specified by:

tan_theta_2 in interface Trigonometrical

Returns:

tan(this/2) in the form of a Approximation.

square

protected BaseNumber square()

Method to yield the square of this value.

Returns:

this * this.

pow

protected BaseNumber pow(int power)

Method to yield the value of this to a power.

Specified by:

pow in class BaseNumber

Parameters:

power - the power to which this must be raised.

Returns:

this ^ power.

pow

protected BaseNumber pow(double power)

Method to yield the value of this to a power.

Parameters:

power - the power to which this must be raised.

Returns:

this ^ power.

makePresentableInstance

public Presentable makePresentableInstance(Presentation presentation)
                                    throws PresentationException

Instance method to convert a Presentation into a Presentable. Ideally, this would be a class method, but such a method cannot be defined in an interface. Nor can it be defined in an abstract class with the intention of overriding it in a subclass. Polymorphism just doesn't work that way.
Therefore, the present value (as in fields) of the instance is essentially ignored - only the methods are important.

Specified by:

makePresentableInstance in interface Presentable

Parameters:

presentation - a NumberPresentation to be converted into an Approximation.

Returns:

an Approximation in the form of a Presentable.

Throws:

PresentationException - in case of parsing error or if the presentation is not a NumberPresentation.

floatValue

public float floatValue()

Method to yield this value as a float.

Specified by:

floatValue in class BaseNumber

Returns:

doubleValue as a float.

minus

protected BaseNumber minus()

Method to return this but with changed sign.

Specified by:

minus in class BaseNumber

Returns:

- this

toString

public java.lang.String toString()

Method to represent this object as a string.

Overrides:

toString in class Item

Returns:

the string corresponding to this approximation.

See Also:

Item.present(), Presentation.toString()

test

void test(java.io.PrintStream output,
          java.lang.String name)

main

public static void main(java.lang.String[] args)

Test program.

Parameters:

args - ignored.

IntrinsicError

static double IntrinsicError(int halfplaces)

Method to get the intrinsic error of a number accurate to 1/2 half-places significant figures.

Parameters:

halfplaces - the number of significant half-places (must be positive).

Returns:

10^(-halfplaces/2) / 2.

IntrinsicError

static double IntrinsicError()

Method to get the intrinsic error of an ordinary double number.

Returns:

the approximate intrinsic error of such a number.

RootSumSquare

static double RootSumSquare(double x,
                            double y)

General method to yield the root-sum-square of two numbers, or in other words the length of the hyponteneuse of a right-angled triangle where x and y are the lengths of the two sides of the triange which include the right angle.

Parameters:

x - either of the two numbers (order is immaterial).

y - the other of the two numbers.

Returns:

sqrt(x^2 + y^2);