Welcome

Magnitude is a Java library to do mathematical operations using physical quantities (value with units). Change in the units and units validation is automatically performed as operations are performed on the physical quantities. This library is an adaptation from Juan Reyero’s Magnitude library for Python.

For more information, please refer to the javadoc.

Examples

Operation

Performing mathematical operations using magnitude is easy. Simply created two Magnitude objects and use the right method to perform the operation:

Magnitude u = new Magnitude(5, "m");
Magnitude v = new Magnitude(2, "s");

Magnitude w = u.div(v);

The result of the division is stored in a new Magnitude object. Different methods are available to retrieve the value as a double:

• by specifying the output units:

  w.getValue("m/s"); // 2.5
  

• from the base units derived from the SI units (kg, m, s, etc.):

  w.getBaseUnitsValue(); // 2.5
  

• by setting preferred units:

  w.setPreferredUnits("km/s");
  w.getPreferredUnitsValue(); // 0.0025
  

Division and multiplication by scalar value are also possible:

w.multiply(3);
w.getValue("m/s"); // 7.5

As quantities with different units cannot be added or subtracted, these operations validates the units:

u.add(v); // throws IllegalArgumentException

Other basic operations include power of and modulo, as well as most of the functions in java.lang.Math. Please refer to the javadoc for more information.

Units

Units of a quantity are given as a string. The default base units are the following: kg, m, s, K, A, mol, cd, rad, sr and px. Other derived units are also available: degC, deg, %, V, J, eV.

The users can register other units to be used to create Magnitude objects. For example, if we want to register the units for “hour” (hr), a Magnitude object representing this new units as base units should be created and then registered:

Magnitude.addMag("hr", new Magnitude(3600, "s"));

Using this new units, the following unit conversion can be made:

Magnitude u = new Magnitude(1800, "s");
u.getValue("hr"); // 0.5

The following prefixes can be used in front of any units to change their magnitude:

prefix	quantity	name
y	1e-24	yocto
z	1e-21	zepto
a	1e-18	atto
f	1e-15	femto
p	1e-12	pico
n	1e-9	nano
u	1e-6	micro
m	1e-3	mili
c	1e-2	centi
d	1e-1	deci
k	1e3	kilo
M	1e6	mega
G	1e9	giga
T	1e12	tera
P	1e15	peta
E	1e18	exa
Z	1e21	zetta
Y	1e24	yotta

For example:

Magnitude u = new Magnitude(89, "nm");
u.getValue("um"); // 0.089

There are different ways to define a multi-dimension Magnitude object (different types of units). For example, the units of velocity (meters per second) can be m/s or m.s-1. For a slightly more complex units, let’s take the Newton (kilogram meter per second squared). The string for this units would be kg.m/s2 or kg.m.s-2. Another example, the Weber (kilogram meter squared per second squared per ampere) would be kg.m2/s2.A or kg.m2.s-2.A-1. Note that the following syntax is not accepted: kg.m2/s2/A.

A few final notes about the units:

• A Magnitude can be unitless:

  Magnitude u = new Magnitude(9);
  

• It can have a value of infinity or “Not a Number”:

  Magnitude u = new Magnitude(Double.POSITIVE_INFINITY, "m");
  Magnitude v = new Magnitude(Double.NaN, "m");
  

• A units can be fractional:

  Magnitude u = new Magnitude(5, "m0.5");
  

Download

The current version is 0.2.5. The library is licensed under the GNU Lesser General Public License v3.

Binary

Two binary packages are available:

• (default) core magnitude package that includes the Magnitude class and extra classes to perform statistical and mathematical operations with Magnitude objects as well as GUI fields in Swing.
• testing magnitude package that includes a Assert class to facilitate testing with JUnit.

A special package is also available for the JDK 1.5.

Ivy repository

The following resolver should be added to ivy settings to retrieve the library:

<url name="magnitude">
    <ivy pattern="http://magnitude.sf.net/ivy/[revision]/ivy.xml" />
    <artifact pattern="http://magnitude.sf.net/ivy/[revision]/[artifact](-[type]).[ext]" />
</url>

To combine this resolver with the default maven repository, use a chain resolver in your ivysettings.xml:

<ivysettings>
    <settings defaultResolver="default" />
    <include url="${ivy.default.settings.dir}/ivysettings-public.xml" />
    <include url="${ivy.default.settings.dir}/ivysettings-shared.xml" />
    <include url="${ivy.default.settings.dir}/ivysettings-local.xml" />

    <resolvers>
        <chain name="default" returnFirst="true">
            <resolver ref="local" />
            <resolver ref="shared" />
            <resolver ref="public" />

            <!-- Resolver for magnitude -->
            <url name="magnitude">
                <ivy pattern="http://magnitude.sf.net/ivy/[revision]/ivy.xml" />
                <artifact pattern="http://magnitude.sf.net/ivy/[revision]/[artifact](-[type]).[ext]" />
            </url>

            <!-- Any other resolvers -->
        </chain>
    </resolvers>
</ivysettings>

Then add the following dependency to your ivy.xml file to retrieve the core magnitude package:

<dependency org="net.sf.magnitude"
            name="magnitude"
            rev="latest.integration"
            conf="*->runtime" />

or this one to retrieve the testing magnitude package:

<dependency org="net.sf.magnitude"
            name="magnitude"
            rev="latest.integration"
            conf="*->testing" />

Source

The source is available in a zip file or via the Bazaar repository on SourceForge:

bzr://magnitude.bzr.sourceforge.net/bzrroot/magnitude

FindBugs and JUnit are required to compile the code.

Bugs

For any bugs or new features, please refer to the support page on SourceForge.