Package com.rubecula.jquantity

JQuantity

See:
Description

Interface Summary

Arithmetical	Interface to define certain standard Arithmetical accessor methods.
Arithmutable	This interface defines various arithmetical mutating methods.
Divisible	Interface to define Divisible arithmetical operations.
Estimable	The public interface Estimable defines the methods which allow an object to maintain a visible, up-to-date estimate of its value for debugging purposes.
Fuzzy	This interface specifies the methods which characterize a fuzzy value: getBoundAbs, getBound, getModel.
FuzzyMutable	This interface specifies the methods which allow setting fuzzy data: setBoundAbs, setBoundRel, setModel.
FuzzyPresentable	This interface defines operations required for presenting fuzzy objects.
Imaginable	Imaginable: the interface which defines complex operations.
Integral	Interface to define Integral operations.
Measurable	This interface specifies the methods which characterize a measurable (i.e.
Millable	This interface is implemented by objects which can be operated on by a mill, i.e.
Mutable	This interface is used to define whether an object is mutable, that is to say it has non-final instance fields with mutator methods. Note that any object which is mutable cannot properly (and safely) be copied other than by cloning (this is a fact of Java life). Objects which are themselves immutable but which reference Cloneable objects must implement Cloneable and the clone method must clone any referenced instances which are Cloneable.
Normalizable	This interface defines the operation which can be invoked on an object to "normalize" it.
Transcendental	This interface models the functions necessary for evaluating transcendental functions.
Trigonometrical	This interface defines trigonometrical operations.

Class Summary

Approximation	This Class approximates a value using an immutable double-precision value.
BaseNumber	Abstract (scalar) numerical class from which to derive other concrete classes.
BaseUnit	This abstract class represents, in its most primitive form, a unit of the Systeme International (SI).
Complex	Representation of a Complex Number
Dimensions	The public class Dimensions represents pure dimensional information - no scaling or other information.
DivisibleMutable	Interface to define Mutating Divisible arithmetical operations.
Expression	Class to manage a mathematical expression.
FlatUnit	The public class FlatUnit is used to describe a Measurable which has been flattened out so that all its dimensions and its scale are readily apparent.
FuzzInt	This class extends a WholeNumber by adding fuzzy parameters.
IntegerPresentation	Presentation class to deal with integral objects in radix 10.
Item	Abstract base class from which to derive other more concrete classes.
JQuantity	This class represents a quantity, that is to say a value and its units.
JQuantityPresentation	This class is a string-component representation of a JQuantity.
Loader	This public class is used to populate the JQuantity system at run-time with various definitions of units, etc.
Manifest	This class defines a "manifest" constant (a whole number which cannot be changed).
Mill	This class is responsible for evaluating operations on Presentable objects.
MillFactory	Factory class for Mills.
MutableNumber	Abstract class from which to derive other concrete classes of mutable numbers.
NumberPresentation	Public class used primarily for the output of instances of Rational.
Operator	This class defines operators in the context of SymbolicPresentations and their Presentable counterparts: Expressions.
PresentableFactory	Factory class for creating Presentables from double or long values (the preferred method of creating Presentables is to start with a String, create a Presentation using an implementer of PresentationFactoryInterface, and then turn that into a Presentable).
PresentationFactory	Factory class for Presentations.
QuantityPresentation	Presentation class to deal with quantity objects.
Rational	Public class to represent precise rational numbers.
SiUnit	This class represents, in its most primitive form, a unit of the Systeme International (SI).
SymbolicPresentation	Class to model the presentation of symbolic text, for example in a mathematical formula.
SystemFlag	The immutable class SystemFlag represents a system of units.
Units	This class extends UnitsFoundation by adding instance fields: _A, _B, _PowerA, _PowerB, _Scale, _Offset and _System.
UnitsFoundation	The public abstract class UnitsFoundation is the base class from which the other Units (Measurable) classes are derived.
UnitsName	The class UnitsName is used to identify units.
UnitsTable	This class extends HashMap to provide a table of units values.
Value	This class represents a Rational which may be factored in some way.
ValuePresentation	Presentation class to deal with value objects.
WholeNumber	This class is a logical extension of the BigInteger class, but is an actual extension of MutableNumber.

Exception Summary

Expression.ExpressionException	Static class to define an exception encountered when parsing a formula.
InvalidOperandException	A checked exception intended to be internal to the JQuantity package, which indicates that when a mathematical operation A op B is invoked, the class of B is not valid for the operation on A.
JQuantityException	This exception class is used to report problems in the JQuantity package.

Package com.rubecula.jquantity Description

JQuantity

Contents:

• Copyright Notice
• Overview
• JQuantity Philosophy
• Programming Conventions
• Class Structure
• Links

Copyright Notice

JQUANTITY Framework Project.
Copyright (C) 2002, 2003 Rubecula Software.
This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

CVS Version: $Revision: 1.7 $

Back to Top

Overview

The following text was provided to SourceForge to describe this project:

The purpose of this project is to make available a set of Java classes which enable end users and programmers to make scientific calculations resulting in either exact quantities or quantities with known (bounded) errors.

Previously developed in the form of an end-user applet supported by beans, this project will remodel the classes for more general usage including end-user usage as a servlet or SOAP-enabled RPC.

The primary class is JQuantity. An instance of JQuantity includes the actual value (i.e. the best approximation of the value), the current precision (error bounds) and the units.

Numbers may be real or complex. JQuantity calculations use a method of lazy evaluation of transcendental-function-based quantities which either reduces or eliminates possible errors. Non-transcendental quantities are represented as rational numbers. Non-zero errors, where needed, can be characterized as uniform or Gaussian.

Methods allow representation of a JQuantity in the most appropriate text form, given a user-preferred system of units.

An extensible library of standard constants is provided. A JQuantity stack (of semi-infinite size) is provided which supports most of the standard mathematical functions. Non-supported esoteric functions can be added by accessing other calculator programs, e.g. unix calc, or by simply using the macro programming capability.

For usage as a serious online calculator for end-users, a swing-based applet class is provided which allows customization and programmability.

The applet will be extended to allow infix operations in addition to the current RPN operations.

Back to Top

JQuantity Philosophy

Here are some of the tenets of the philosophy behind the design and development of JQuantity:

• It is object-oriented and implemented in Java.
• It provides a computing framework for numbers with known uncertainty.
• The code conforms to a set of programming conventions.
• Documentation is an integral part of the package.
• Accuracy is always more important than performance.
• It is extensible.
• It is open-source: comments and constructive criticism are welcomed.
• It is independent of commercial interests.
• It has the potential to become part of the Java Grande Numerics computing framework.

Back to Top

Programming Conventions

• Factory methods (public static Class method(...)) always return a new object; whereas instance methods which return Class might not. Note: there are at least some situations where a factory method returns an instance of a superclass rather than the class itself (i.e. not all classes redefine all possible factory methods).
• The order of source files is generally: public class fields, public class methods, public instance methods, non-public instance fields, non-public instance methods. Some variations occur because of requirements of static initialization (some private class fields may appear first).
• Naming: class fields and methods generally begin with capital letters (exceptions when name is a Java convention such as valueOf); instance fields are of the form _Class or similar; constants (final static fields) have names beginning with "$".

Back to Top

Class Structure

The following is an introduction to the major classes and interfaces of the jquantity package. Use it as a starting point and/or as an adjunct to the javadoc. However, if there are discrepancies, then the javadoc must of course take should be considered definitive.

Before describing the numerical classes proper, it is important to mention two (co-) utility classes (in the util package):

• Presentation: this abstract class is used to model a structured text presentation of an opaque object. Except in the case of an IntegerPresentation, there will always be more than one string which defines the presentation. A Presentation can be rendered as a single string of finite length using the toString(int) method. Further, a Presentation can be parsed into a Presentable object (see next item below) using the parse() method.
• Presentable: this interface is implemented by all classes which can be "presented" by a Presentation object (see previous item above) using the present(AttrMap) method. Thus, all numerical classes in the jquantity package implement Presentable.

Note that the two classes Presentation and Presentable are co-dependent (this is the only situation in the jquantity package where two classes are mutually dependent).

Following are descriptions of the significant jquantity classes.

• Item: this abstract class is extended by all most of the classes in the jquantity package. Thus, it should be the starting point for any examination of the details of the package. Item implements:
  • Presentable,
  • Auditable which is useful for identifying items for testing purposes,
  • java.lang.Comparable which allows items to be compared with each other and thus ordered in some sense,
  • java.lang.Serializable which allows items to be (potentially) persisted.
• BaseNumber: this concrete class is extended by all scalar numerical classes in the jquantity package. BaseNumber, extends Item, reimplements java.lang.Number [wish Java had true multiple inheritance] and implements:
  • Millable,
  • Arithmetical which defines various arithmetical accessor methods,
  • Fuzzy which defines a set of accessor methods which can be used to quantify the uncertainty of a numerical object,
• MutableNumber: this abstract class is extended by all scalar numerical classes in the jquantity package which can be mutated (that is to say all except Manifest and JQuantity). In turn, MutableNumber extends BaseNumber and implements:
  • Identifiable which is a mutating class related to Auditable,
  • Arithmutable which is a mutating numerical operations class related to Arithmetical [Note that all mutating classes in jquantity, including Arithmutable, implement the Mutable interface, which in turn implements the java.lang.Cloneable interface].
• WholeNumber: this concrete class models mutable and potentially fuzzy integers [Actual fuzzy integers are instances of FuzzInt which extends WholeNumber]. WholeNumber extends MutableNumber and implements:
  • Integral which defines various integer arithmetic methods,
  • Estimable, another interface helpful when debugging classes involving objects without an obvious "value" such as Rational or WholeNumber.
• Manifest: this concrete class models immutable integers for the purpose of defining integer constants. Manifest extends BaseNumber and implements: Integral see above (WholeNumber).
• Fuzzy: this interface describes the precision of an object. In particular, it defines an error model which is either None, Uniform or Gaussian; as well as an error bound. In the case of None, the bound is ignored; in the case of Uniform, the error distribution is considered to be a rectangular step symmetrical about the nominal value and of total length 2 bound; in the Gaussian model, the distribution is considered to be normal with mean at the nominal value and a standard deviation equal to bound.
  
• Approximation: this concrete class models immutable fuzzy floating point values. Indeed, a better name for this class might be "Irrational" since any rational value is expected to be modeled using Rational. Approximation extends BaseNumber and implements Arithmetical, Fuzzy, Presentable, etc. The instance fields are its value (a double), its relative bounds (double) and the error model (an int, according to Fuzzy)
  
• Rational: this concrete class models mutable ratios as a pair of Integral numbers. Specific instances of the numerator and denominator might be WholeNumber, FuzzInt, or Manifest depending on needs and fuzziness. Rational extends MutableNumber and implements:
  • Divisible which defines methods which can in general transform integers (non-integers) into non-integers;
  • FuzzyMutable which defines a set of mutating methods related to Fuzzy;
  • Trigonometrical which defines various trigonometrical methods;
  • Normalizable an interface implemented by classes with more than one instance fields such that it may be possible to "normalize" the relationship between these fields;
  • Estimable see above (WholeNumber).
• Value: this concrete class is a sub-class of Rational, with the addition of a factoring scheme.
  There are at present three factoring schemes: None (i.e. 1), Pi and E. Numbers can be represented as exact multiples of any of these three factoring schemes.
• JQuantity: this concrete class models immutable dimensioned quantities, that is to say numbers with associated units. The two instance fields are a BaseNumber and a Units. Rational extends BaseNumber and implements:
  • Measurable which defines methods relating to units and which is also implemented by all classes which represent units, including Units;
  • Cloneable;
• Complex: this concrete non-scalar numerical class models complex mathematical objects, that is to say quantities with a real and an imaginary component. It extends Item and supports the mathematical operations afforded by the addition of the imaginary component (viz. those defined in Imaginable) as well as the Trigonometrical functions. It also implements Millable, Divisible, and other interfaces.
• In future versions, Hypervalues, Quaternions and numerical arrays may be implemented as other subclasses of Item

Back to Top

Links:

• JQuantity Home Page
• Source Forge Project Page: JQuantity
• About JQuantity
• JEP Home Page
• Java Grande Numerics Working Group

Back to Top

Last Updated: 2003-10-16