Package com.rubecula.jquantity

JQuantity Contents: Copyright Notice Overview JQuantity Philosophy Programming Conventions Package Structure
Class Structure Links Important Note about the links to classes in this document: This document appears in two different places: the source tree and the doc tree (where it is placed by the javadoc program).

See:
Description

Interface Summary

Arithmetical	Interface to define certain standard Arithmetical accessor methods.
Arithmutable	This interface defines various arithmetical mutating methods.
CompoundModel	Class
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.
Millable	This interface is implemented by objects which can be operated on by a mill, i.e. something which implements MillInterface.
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.
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.
AttributeFactory	Class
Attributes	Class
BaseNumber	Abstract (scalar) numerical class from which to derive other concrete classes.
Complex	Representation of a Complex Number Objects of this class represent complex numbers defined on one side or the other of the EL (exponential-log) plane.
Compound	Class
Constants	Class to create Lookupable objects for the JQuantity framework.
DivisibleMutable	Interface to define Mutating Divisible arithmetical operations.
Expression	Class to manage a mathematical expression.
FuzzInt	This class extends a WholeNumber by adding fuzzy parameters.
IntegerPresentation	Presentation class to deal with integral objects in radix 10.
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.
Library	Class which defines constants, formulas, etc. for use in a Mill.
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.
MutablePresentation	Class
NumberPresentation	Public class used primarily for the output of instances of Rational.
OneMatrix	Class to model a fixed-size one-dimensional matrix (normally called a Vector) but given the name OneMatrix to avoid confusion with Vector.
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.
QuantityProperties	Class to model JQuantities which can be read from a properties file, stored back and looked up (using a key string) the application.
Rational	Public class to represent precise rational numbers.
Row	Class
SparseMatrix	Class
SymbolicPresentation	Class to model the presentation of symbolic text, for example in a mathematical formula.
TwoMatrix	Class to represent a fixed size two-dimensional matrix.
Value	This class represents a Rational which may be factored in some way.
Value.transcendental2Arctan
Value.transcendentalExp
Value.transcendentalLog
Value.transcendentalSqrt
Value.transcendentalSquare
Value.transcendentalTanThetaBy2
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.
Value.ValueException

Package com.rubecula.jquantity Description

JQuantity

Contents:

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

Important Note about the links to classes in this document: This document appears in two different places: the source tree and the doc tree (where it is placed by the javadoc program). The class links are only valid when reading the version in the doc tree.

Copyright Notice

JQUANTITY Framework Project.
Copyright (C) 2002, 2003, 2004 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.10 $

Back to Top

Overview

The following text was provided to SourceForge to describe this project [note that some of this may now be outdated]:

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 "$".

Note two things, however. Although most of the code has its roots in an earlier implementation (of Calculator.NET), much of it has been completely rewritten more or less from scratch. However, some parts (notably those dealing with Units) have not yet been scrubbed convention-wise. Furthermore, conventions change somewhat, especially in the light of the Eclipse Workbench which I am now using to develop the code. This has its own ideas of the appropriate ordering of source code.

Back to Top

Package Structure

Most of the numeric classes are in the package called com.rubecula.jquantity. At some future time, this will be split further with the purely numeric going into a package called com.rubecula.numeric (or similar), and the presentation-related classes going into com.rubecula.presentation (or similar). The classes remaining in jquantity will probably be have to do with expression parsing, units, compound numbers like Complex, etc.

Other packages related to JQuantity are:

• The package com.rubecula.util contains utility classes, not just those for usage by JQuantity.
• The package com.rubecula.math contains classes which know how (or can be taught) how to perform advanced mathematical operations.
• The package com.rubecula.units contains the classes which relate to units of quantities (meters, kilograms, feet, etc.). The units package is essentially a "co-package" with the jquantity package as the imports are not all unidirectional. It is more of a convenience in grouping.
  
• The package com.rubecula.jep is an expression parser which uses the third-party package org.nfunk.jep (JEP).

The remainder of this document (or at least, most of it) describes the jquantity package in more detail.

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 (or possibly here: 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 most of the classes in the jquantity package. Thus, it should be the starting point for any examination of the details of the package. [Note that Item is found in the util 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. JQuantity 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;
  • Divisible.
• 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.
• Attributes which typically control the presentation of objects are defined in the Attributes class which extends the com.util.AttrMap class.
• QuantityProperties is a class which allows the definition of properties in a file. It extends com.util.ConvenientProperties.
  
• In future versions, Hypervalues, Quaternions and numerical arrays may be implemented as other subclasses of Item. The classes Compound and CompoundModel have been added to facilitate the development of such objects. At present, skeletal classes for OneMatrix, TwoMatrix, SparseMatrix, Row have been added.
• 
  

Back to Top

Links:

• JQuantity Home Page
• Source Forge Project Page: JQuantity
• About JQuantity
• JEP Home Page
• Java Grande Numerics Working Group
• International System of Units from NIST:

Back to Top

Last Updated: 2004-01-31