Java Package for Physical Units and Unit Conversion

About the Library -- Using the Library -- Downloading and Installing -- Modifying the Code

About The Library

The unit library is for use in engineering or scientific applications where the user wishes to input numbers in one unit system, and the application needs numbers in a different system.

Units can be created from an arbitrary combination of the built in units at run time. For example, if an area is required, the user can input "m^2" or "in^2". Error checking can be performed to make sure that a specified unit is of the correct type. For example, "m" is not the same as "m^2".

The code can then convert numbers from this unit to the corresponding SI unit, and visa versa. Typically, an application will be programmed to work in SI units, and do all conversion during input and output. However, conversion can be done at any stage.

Whenever a new unit is created, it is stored in a table of units so that it may be used in the definition of other units, later on.

See the Main Page or the Sourceforge Project Page for more information, and for information about the companion program, a PalmOS application.

Using the Library

A rough overview is given here, which should be sufficient for most uses. For a complete description of all methods and classes, as generated by javadoc, see the API page.

To convert numbers from one unit to another, an application would typically first create two Unit objects representing the desired units. Second, the two objects may be compared to verify that they are compatible. Third, the numbers are converted from the first unit to SI units. And finally the numbers are converted from SI units to the second unit.

To create a unit object you would use one of these:

All of these can throw Unit.ParseException if the string that is parsed has an error in it. There are no public constructors for Unit, you must use one of these static "factory" methods.

Once the units are created, you can use the following three methods:

For example, a subroutine that converts a number into millimeters would look something like this:

double convertToMillimeters(String unit1, double x) throws ParseException {
	Unit u1 = Unit.newUnit(unit1);
	Unit u2 = Unit.newUnit("mm");
	if( ! u1.sameType(u2) ) {
		System.out.println("Warning: "+u1+" not compatible with "+u2);
	double x_si = u1.from(x);
	double x2   =;
	return x2;

You may also create new units, which are not named as the product or quotients of other units. You may wish to do this if you are parsing an equation of some sort. The methods to use are:

These do not put u3 in the table of existing units, because it is not generated with a name. Since sums and differences should be of equivalent units, you would just use sameType.

See the list of units page for a list of built in units and prefixs, and a more detailed description of how the string is parsed in order to create a unit.

One last note: If you would prefer to use lb for pound mass, you can have the code
Unit.newUnit("lb", 1, "lbm");
before you create any units with a pound in them. This will create a new unit with the same name as the old one, but with a new definition. This new Unit is then stored in the internal table of units under the name "lb". Now, any more calls to newUnit will use this new definition of "lb".

Downloading and Installing

You may download a jar file from sourceforge download page. This jar has all of the class files in the unit package, as well as those in the jmisc package that are also needed. The jar file does not include any documentation except for this web page.

Consult the documentation for your java virtual machine on how to install a jar file.

From the same download page, you may also download the source files in either a compressed tar file (tgz) or a zip file. This file will include all the java files as well as the C++ source for the PalmOS application. The Java code for unit is in the public domain. The PalmOS application is under the LGPL license.

In order to compile the java code, you will need the jmisc package. A jar file of the jmisc classes is included in the source download.

A makefile is included for compiling. However, the code is standard Java, and may be compiled in the usual manner.

Modifying the Code

If you wish to add a new built-in unit, you should edit and run the file, which will create Typically this is only done when a unit is needed for several different applications.

The parser in this package was created with JavaCC You will need to have this installed if you wish to modify the parser. To compile the existing parser, and the other Java code, you do not need to have JavaCC installed.

Main Page --- Fred Gylys-Colwell --- Last Revised: January 23, 2005 --- Project Page