com.rubecula.jquantity
Class Approximation

java.lang.Object
  |
  +--com.rubecula.jquantity.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.29 $

Author:

Robin Hillyard

See Also:

Serialized Form

Field Summary

(package private) static Approximation	$_alpha Fine structure constant (approx): 7.29735308(33)E-3.
(package private) static Approximation	$_au Astronomical Unit (approx): 1.49597893*E11.
(package private) static Approximation	$_e Electron charge (approx): 1.60217733(49)E-19.
(package private) static Approximation	$_F Faraday constant (approx): 96485.309(29).
(package private) static Approximation	$_G Gravitation constant (approx): 6.67259(85)E-11.
(package private) static Approximation	$_K Boltzmann constant (approx): 1.380658(12)E-23.
(package private) static Approximation	$_mp_me Mass ratio of proton to electron (approx): 1836.152701(37).
(package private) static Approximation	$_R Rydberg constant (approx): 1.0973731534(13).
static Approximation	$1 The constant value of 1 (exact).
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]

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.
(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, Wrap

Methods inherited from class com.rubecula.jquantity.Item

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

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:

java.lang.Math.PI

$e

public static final Approximation $e

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

See Also:

java.lang.Math.E

$_R

static final Approximation $_R

Rydberg constant (approx): 1.0973731534(13).

$_mp_me

static final Approximation $_mp_me

Mass ratio of proton to electron (approx): 1836.152701(37).

$_alpha

static final Approximation $_alpha

Fine structure constant (approx): 7.29735308(33)E-3.

$_e

static final Approximation $_e

Electron charge (approx): 1.60217733(49)E-19.

$_F

static final Approximation $_F

Faraday constant (approx): 96485.309(29).

$_K

static final Approximation $_K

Boltzmann constant (approx): 1.380658(12)E-23.

$_G

static final Approximation $_G

Gravitation constant (approx): 6.67259(85)E-11.

$_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

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.

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.

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.

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.

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);