J.A.D.E.
Java Addition to Default Environment.

      Just as the constant increase of entropy is the basic law of the universe,
      so it is the basic law of life to be ever more highly structured and to
      struggle against entropy!                    Václav Havel

• Customizable XML support for all your classes.
• A Generic Matrix class.
• Automatic error calculation on all operations (including numeric errors).
• More than 400 measurement units for almost 40 different quantities.
• Automatic unit simplification and verification.
• Support for enumerated types.

JADE Version 1.0

This library is a spinoff of the now obsolete Quantity Package.
The binary distribution (executable jar file) includes a subset of the Xerces-1.2.0 XML parser developed by the Apache Software Foundation.

com.dautelle.xml

With this package you will be able to create objects from their XML representation. There is no interface to implement, but you will have to provide a XML constructor (a Java constructor with two arguments, one for the attributes and one for the child elements which are recurcsively created). Namespaces are supported. They map directly to Java packages.

Additionaly, any class which implements the interface com.dautelle.xml.Representable is able to store its instances in XML format.

The following example demonstrates how a heterogeneous Matrix is stored, then retrieved in XML format:

      Matrix M = new Matrix(2, 2);
      M.set(0, 0, new Real(0.0));
      M.set(0, 1, new Complex(0.0, 1.0));
      M.set(1, 0, new Angle(20, 0.1, Angle.DEGREE));
      M.set(1, 1, new ElectricPotential(10, 1, ElectricPotential.VOLT));

      File file = new File("C:/matrix.xml");

      // Save Matrix.
      Properties namespaces = new Properties();
      namespaces.setProperty("com.dautelle.math", "math");
      namespaces.setProperty("com.dautelle.quantity", "quantity");
      ObjectWriter ow = new ObjectWriter(namespaces);
      FileOutputStream out = new FileOutputStream(file);
      ow.write(M, out);

      // Read Matrix.
      Constructor constructor
        = new Constructor("org.apache.xerces.parsers.SAXParser");
      Matrix R = (Matrix) constructor.create(file);

Here is the matrix.xml created, then read.

com.dautelle.math

With this package you will be able to resolve linear system of equations involving any kind of elements. The only requirement being that your elements must implement the interface com.wb.math.Operable (basically any class which defines the primitive operations add, negate, multiply and invert). The classes Real, Complex but also Matrix implement this interface. Therefore nothing prevents you from performing operations on Matrices of Matrices!
More seriously, the combination of physical quantities and matrix operations is a very power tool. Don't forget all physical quantities embed automatic error calculation. Therefore, when you try to resolve a system of equation involving real world quantities, the error on the solution obtained will tell you if can trust that solution or not (i.e. system close to singularity).

Example of resolution of a system of linear equations involving physical quantities:

Let's say you have a simple electric circuit composed of 2 resistors in series with a battery. You want to know the voltage (U1, U2) at the nodes of the resistors and the current (I) traversing the circuit.

          ElectricResistance R1 = new ElectricResistance(100, 10, ElectricResistance.OHM);
          ElectricResistance R2 = new ElectricResistance(300, 30, ElectricResistance.OHM);
          ElectricPotential U0 = new ElectricPotential(28, 0.1, ElectricPotential.VOLT);

          // Equations:  U0 = U1 + U2       |1  1  0 |   |U1|   |U0|
          //             U1 = R1 * I    =>  |-1 0  R1| * |U2| = |0 |
          //             U2 = R2 * I        |0 -1  R2|   |I |   |0 |
          //
          //                                    A      *  X   =  B
          //
          Quantity[][] Aq = {
              {new Dimensionless(1),  new Dimensionless(1),  new ElectricResistance(0, ElectricResistance.OHM) },
              {new Dimensionless(-1), new Dimensionless(0),                      R1                            },
              {new Dimensionless(0),  new Dimensionless(-1),                     R2                            }};
          Matrix A = new Matrix(Aq);
          Quantity[][] Bq = { {U0},
                              {new ElectricPotential(0, ElectricPotential.VOLT)},
                              {new ElectricPotential(0, ElectricPotential.VOLT)} };
          Matrix B = new Matrix(Bq);
          Matrix X = A.inverse().multiply(B);
          System.out.println(X);
          System.out.println("Estimated current = " + ((Quantity) X.get(2, 0)).doubleValue());
          System.out.println("Relative error  = " + ((Quantity) X.get(2, 0)).relativeError());

      > {{7. kg*m*m/A/s/s/s},
      >  {21. kg*m*m/A/s/s/s},
      >  {7.1e-2 A}}
      > Estimated current = 0.07073232323232331
      > Relative error = 0.10353445198144762

As you can see the estimated current (70.73 mA) is higher than the current you would get using real numbers (28.0 / 400.0 = 70mA). Indeed the relationship between the resistors and the current is not linear (I = U/R). As the resistor fluctuates, the current fluctuates as well but not symmetricaly.


com.dautelle.quantity

With this package you can create your own Units or reuse more than 400 standard Units already defined.

If you want to create your own quantities:
You need only two classes (Quantity and Unit), and will still benefit from the following features:
• Unit simplification.
• Run-time checking of Unit consistency.
• Error calculation.
• Matrix calculation.


Example:

          Unit kilo = new Unit("kilo");
          Unit teaspoon = new Unit("teaspoon");
          Quantity densitySugar = new Quantity(2.27, 0.01, kilo).divide(new Quantity(567, 1, teaspoon));
          Quantity massSugarTeaspoon = densitySugar.multiply(new Quantity(1, teaspoon));
          System.out.println(massSugarTeaspoon);

      > 4.00e-3 kilo

Tne number of digits displayed is characteristic of the precision of the measure. In this example the actual mass of a teaspoon of sugar is between 3.90 and 4.10 grams.

If the predefined quantities (such as Length, Duration, Mass...) are used:

You will be able to take advantage of these additional features:
• Unit conversions.
• Compile-time checking of Unit consistency.
• Specific constructors.
• Specific methods, i.e. trigonometric operations for Angle.

All predefined quantities are 100% compatible with the generic Quantity class (they are sub-classes), therefore nothing prevents you from mixing your own quantities with the predefined ones.

Example:

          Length height = new Length(4.6, 0.02, Length.INCH); // Precision of 0.02 Inch
          Length radius = new Length(2.0, 0.02, Length.INCH); // Precision of 0.02 Inch
          Area topArea = new Area(radius, new Angle(1.0, Angle.REVOLUTION));
          Volume canVolume = new Volume(topArea.multiply(height));
          System.out.println("Can volume = " + canVolume.in(Volume.FLUID_OUNCE_US));
          System.out.println("Relative Error = " + canVolume.relativeError());

      > Can volume = 32.0 Fluid_Ounce_US
      > Relative Error = 0.02434370965430697

Tne number of digits displayed is characteristic of the precision of the measure. In this example the actual volume is between 31.0 and 33.0 ounces (2% relative error).

Numeric errors are automatically taken into account!

This can be illustrated with the following example:

          double x=10864, y=18817;
          double z = 9 * Math.pow(x, 4)- Math.pow(y, 4) + 2 * Math.pow(y,2);
          System.out.println("Result using double : " + z);

      > Result using double : 2.0

The mathematically correct value is z=1. However, Java compilers using ANSI/IEEE double precision numbers evaluate z=2. Not even the first digit is correct! This is due to a rounding error occurring when subtracting two nearly equal floating point numbers.
Now, lets write the same formula using physical quantities:

          Dimensionless X = new Dimensionless(10864);
          Dimensionless Y = new Dimensionless(18817);
          Quantity Z = X.pow(4).multiply(9).subtract(Y.pow(4)).add(Y.pow(2).multiply(2));
          System.out.println("Result using physical quantities : " + Z.doubleValue());
          System.out.println("Associated error : " + Z.absoluteError());

      > Result using physical quantities : 2.0
      > Associated error : 448.00000059604645

The same result is returned, but now you know you cannot trust it!


com.dautelle.util

In this package you will find the base class for all enumerated types. It has the following advantages over the usual "static int" declaration:

• It is strongly typed
• It avoids assignment errors (duplications or discontinuities)
• Comparaisons are as fast as their "Integer" counterpart
• Enumerates can be used in a switch or as array index for direct access (pos())
• They are Serializable.
• The complete collection is accessible.


The following code defines three enumerated colors and print them:

      public final static class Color extends Enumerate {
          public static final Color RED = new Color("red");
          public static final Color BLUE = new Color("blue");
          public static final Color GREEN = new Color("green");

          public static final Color all = new Color(null);
          private Color(String name) { super(name); }
      }

      for (Iterator i = Color.all.iterator() ; i.hasNext() ;)
          System.out.println(i.next());