Java Ultimate Math Package
White paper
Home 
Statistics
date:  199806.22
author:  Ernst de Haan
version:  3 (199809.24)
On this page: Specification statistics | Overview | Goals | Class diagram | API overview | Issues | Example | Future directions | Further reading | Feedback 
Specification statistics
version:  1.0a4 (199809.24)
owner:  Utrecht University, The Netherlands
authors:  Ernst de Haan
copyright:  GNU General Public Library License
platform:  Java 1.1 or higher
:
Overview
The Java Ultimate Math Package (JUMP) is a library that offers arbitrary precision mathematical computations. 

The library is based on the JavaBeans architecture. JUMP is based on an open specification, a free reference implementation is provided. It does not contain native code and does not rely on platform specifics. 

The API is in the package nl.coffee.math. It will be part of COFFEE, the ClassMate Open Framework For Educational Environments.

:
Goals
The main goals of the Java Ultimate Math Package are: 
  • provide a base class for real, rational and integer numbers and a uniform way to perform calculations on instances
  • provide arbitrary precision integer and non-integer numbers, that do not suffer from floating-point platform-specifics, like the Pentium FPU bug
  • provide a smooth transition from native datatypes (i.e. float, double, etc.) and JDK number types (i.e. BigInteger, BigDecimal) to and from the JUMP classes
This pre-release version of the JUMP only includes a basic functionality, other features will be included in future releases.
:
Class diagram
This diagram show the main interfaces in the API: 
:
API overview
Below is an overview of the most important methods of the main classes/interfaces in the API, with a short description. For a complete reference see the API documentation. 
 
RealNumber (interface) 
An immutable real number.
boolean   getSign()
int   compareTo(RealNumber)
RealNumber   abs()
RealNumber   negate()
RealNumber   invert()
RealNumber   add(RealNumber)
RealNumber   subtract(RealNumber)
RealNumber   multiply(RealNumber)
RealNumber   divide(RealNumber)
RealNumber   pow(RealNumber)
IntegerNumber   trunc()
long   longValue()
double   doubleValue()
BigDecimal   toBigDecimal(int precision, int roundingMode)
RationalNumber (interface) extends RealNumber 
Base for all signed rational numbers.
IntegerNumber   getNumerator()
IntegerNumber   getDenominator()
IntegerNumber (interface) extends RationalNumber 
Base for all signed integer numbers.
IntegerNumber   fac()
IntegerNumber  integerDivide(IntegerNumber)
IntegerNumber   remainder(IntegerNumber)
IntegerNumber   gcd(IntegerNumber)
BigInteger   toBigInteger()
BigDecimal   toBigDecimal()
CompositeNumber extends RealNumber 
Interface for composite real numbers.
RealNumber []   getElements()
int   getElementCount()
RealNumber   getElement(int index)
NumberFactory (interface) 
Factory that produces RealNumbers. Provides a flexible way to convert native Java numbers to JUMP numbers.
IntegerNumber  createIntegerNumber(byte[])
RationalNumber   createFraction(IntegerNumber numerator, IntegerNumber denominator)
IntegerNumber   valueOf(long)
RationalNumber   valueOf(double)
IntegerNumber   valueOf(BigInteger)
RationalNumber   valueOf(BigDecimal)
static NumberFactory   getDefaultFactory()
static void   setDefaultFactory(NumberFactory)
BasicRationalNumber extends AbstractRationalNumber 
Concrete implementation of a fraction.
BasicRationalNumber   createInstance(IntegerNumber numerator, IntegerNumber denominator)
BasicIntegerNumber extends AbstractIntegerNumber 
Concrete implementation of an integer number, based on a java.math.BigInteger.
BasicIntegerNumber   createInstance(BigInteger)
LongIntegerNumber extends AbstractIntegerNumber 
Concrete implementation of an integer number, based on a long.
LongIntegerNumber   createInstance(long)
 
:
Issues
Although the current 1.0a3 release is still an alpha, the interfaces as defined are expected to change little. There are a couple of issues concerning the current design and implementation: 
  • Class and interface names 

  • IntegerNumber is quite a long name for an interface, but Integer is already in java.lang and we don't want a naming collision with that package. On the other hand, naming should be symmetric, so using "Real", "Rational" and "IntegerNumber" is not an option. 
  • Performance 

  • Performance may be an issue. The pow(IntegerNumber) operation is fairly slow. The sections that check that the argument is not null should be replaced by a try-catch block that catches NullPointerExceptions. This will improve performance. 
  • Java syntax 

  • The Java syntax is quite restricting in some cases. Though it is conceptually beautiful to narrow the return type of an overridden method, the Java language does not permit this. This restriction is recognized, and JavaSoft considers a change to the language syntax. 
  • Rounding
    Though the current version does not support various rounding methods, rounding is critical to JUMP, as we want to display decimal results after performing some arbitrary precision computation. The implementation of generic rounding algorithms for say sines and powers are not straightforward.
  • Comparing
    How does one compare an logarithm to a sine or a fraction to a power. The compareTo(RealNumber) in the RealNumber interface declares that it may throw a CanNotCompareException.
:
Example
See the package nl.coffee.math.test for examples and demos.  The source of this package is included in the source ZIP file, the classes are included in the JAR file. See below for links to these files.
:
Future directions
Future releases are to be packed with new functionality, including: 
  • Additional compound number classes 

  • RealNumber derivates that implement the operations like logarithm, sine, cosine, tangens, arcsine, arccosine, arctangens. 
  • Constants 

  • Classes for constants like pi and e.
  • Rounding
    A class or interface RoundedNumber that implements a rounded number, much like java.math.BigDecimal.
    (expected in next release)
  • Matrix and vector classes
    Matrix and vector interfaces and concrete implementations that work on RealNumber instances.
    (expected in next release)
:
Further reading
Follow these links for more info on the JUMP specification:  The Common Patterns Framework (COPF) extends the horizon of JUMP by adding expressions: 

If you have any comments, suggestions, etc. please mail Ernst de Haan at znerd@hotmail.com


Valid HTML 4.0!Page counterMozilla