Version 1.89.J01 - 3 April 2012. (This page updated 5 April 2014.)

`Units` is a program for computations on values expressed in terms
of different measurement units.
It is an advanced calculator that takes care of the units.

Previously this place contained an applet where you could try the calculations. At present, Java blocks unsigned applets, so you can only see a screenshot of a calculation:

We calculated here the time taken by a stone thrown into a 50-foot well
to reach the bottom.
We used the well-known formula: `square root of 2h/a`
where `h` is the height of the fall and `a` is the
gravitational acceleration, which we knew to be 981 cm/sec^2.
Note that we used different units of length for `h` and `a`,
and the calculator made the necessary conversion behind the scenes.

If you want to try `Units`, you have to install it in on your computer.
As it is written in Java, you can use it under any
operating system that supports Java Runtime Environment (JRE) release 1.5.0 or later.
To install `Units`,
download the Java archive (JAR) file
that contains the executable Java classes.
Save the JAR file in any directory,
under any name of your choice, with extension `.jar`.
If your system has an association of `.jar` files
with `javaw` command (which is usually set up
when you install JRE), just double-click on the JAR file icon.
If this does not work, you can type

java -jarjarfile

at the command prompt,
where *jarfile* is the name you gave to the JAR file.
Each way should open a window like the one shown above.

`Units` supports complicated expressions and a number of mathematical functions,
as well as units defined by linear, nonlinear, and piecewise-linear functions.
See under Expressions for detailed specifications.

`Units` has an extensive data base that,
besides units from different domains, cultures, and periods,
contains many constants of nature, such as:

pi ratio of circumference to diameter c speed of light e charge on an electron h Planck's constant

As an example of using these constants,
suppose you want to find the wavelength, in meters, of a 144 MHz radio wave.
It is obtained by dividing the speed of light
by the frequency.
The speed of light is 186282.39 miles/sec.
But, you do not need to know this exact number.
Just enter this after `You have`:

c / 144 MHz

Enter `m` after `You want` and hit the `Enter` key.
You will get this result:

c /144MHz = 2.0818921 m

Sometimes you may want to express the result as a sum of different units,
for example, to find what is 2 m in feet and inches.
To try this, enter `2 m` after `You have`.
Then enter after `You want`:

ft;inand hit

2 m = 6 ft + 6.7401575 in

Other examples of computations:

Feet and inches to metric: 6 ft + 7 in = 200.66 cm Time in mixed units: 2 years = 17531 hours + 37 min + 31.949357 sec Angle in mixed units: radian = 57 deg + 17 ' + 44.806247 " Fahrenheit to Celsius: tempF(97) = tempC(36.111111) Electron flow: 5 mA = 3.1207548e16 e/sec Energy of a photon: h * c / 5896 angstrom = 2.1028526 eV Mass to energy: 1 g * c^2 = 21.480764 kilotons tnt Baking: 2 cups flour_sifted = 226.79619 g Weight as force: 5 force pounds = 22.241108 newton

(The unit `pound` is a unit of mass.
To get force, you multiply it by
`force`, which is a name for standard gravity acceleration.
Note that `g`, customarily used for that constant,
is already taken as the standard abbreviation for
the gram).

You can explore the units data base with the help of the four buttons
under `You have` field.
By entering any string in `You have` field
and pressing the `Search` button, you obtain a list
of all unit names that contain that string as a substring.
For example, if you enter `year` at `You have`
and press `Search`, you get a list of about 25 different kinds of year,
including `marsyear` and `julianyear`.

Pressing `Definition` displays this in the result area:

year = tropicalyear = 365.242198781 day = 31556926 s,

which tells you that `year` is defined as equal to `tropicalyear`,
which is equal to 365.242198781 days or 31556926 seconds.

If you now enter `tropicalyear` at `You have`
and press the `Source` button, you open a browser on the unit data base
at the place containing the definition of `tropicalyear`.
You find there a long comment explaining that unit.
You may then freely browse the data base to find other units
and facts about them.

Pressing `Conformable units` will give you a list of all units
for measuring the same property as `tropicalyear`,
namely the length of a time interval.
The list contains over 80 units.

With `Units` installed on your computer,
you can use it interactively from command line,
or invoke it from scripts.
It imitates then almost exactly
the behavior of GNU Units from which it has evolved.
See Command interface for details.

You also have a possibility to modify the file that contains unit definitions, or add your own definitions in separate file(s).

The complete package containing the JAR and the Java source can be downloaded as a gzipped tar file from the SourceForge project page.

You use expressions to specify computations on physical and other *quantities*.
A quantity is expressed as the product of a *numerical value* and a *unit of measurement*.
Each quantity has a *dimension* that is either one of the basic dimensions
such as length or mass, or a combination of those.
For example, `7 mph` is the product of number `7` and unit `mile/hour`;
it has the dimension of length divided by time.
For a deeper discussion, see articles on
physical quantity and
dimensional analysis.

For each basic dimension, `Units` has one *primitive unit*:
`meter` for length, `gram` for mass, `second` for time, etc..
The data base defines each non-primitive unit in such a way that it can be converted
to a combination of primitive units.
For example, `mile` is defined as equal to `1609.344 m`
and `hour` to `3600 s`.
Behind the scenes, `Units` replaces the units you specify by these values,
so `7 mph` becomes:

7 mph = 7 * mile/hour = 7 * (1609.344*m)/(3600*s) = 3.12928 m/s

This is the quantity `7 mph` *reduced to primitive units*.
The result of a computation can, in particular, be reduced to a number,
which can be regarded as a dimensionless quantity:

17 m / 120 in = 5.5774278

In your expressions, you can use any units named in the units data base.
You find there all standard abbreviations, such as `ft` for `foot`,
`m` for `meter`,
or `A` for `ampere`.

For readability, you may use plural form of unit names, thus writing,
for example, `seconds` instead for `second`.
If the string you specified does not appear in the data base,
`Units` will try to ignore the
suffix `s` or `es`.
It will also try to remove the suffix `ies`
and replace it by `y`.
The data base contains also some irregular plurals such as `feet`.

The data base defines all standard metric prefixes as numbers.
Concatenating a prefix in front of a unit name means multiplication
by that number.
Thus, the data base does not contain
definitions of units such as `milligram` or `millimeter`.
Instead, it defines
`milli-` and `m-` as prefixes
that you can apply to `gram`, `g`, `meter`, or `m`,
obtaining `milligram`, `mm`, etc..

Only one
prefix is permitted per unit, so `micromicrofarad` will fail.
However, `micro` is a number,
so `micro microfarad` will work and mean `.000001 microfarad`.

Numbers are written using standard notation, with or without decimal point.
They may be written with an exponent, for example `3.43e-8`
to mean `3.43` times `10` to the power of `-8`.

By writng a quantity as `1.2 meter` or `1.2m`,
you really mean
`1.2` multiplied by `meter`.
This is multiplication denoted by *juxtaposition*.
You can use juxtaposition, with or without space, to denote multiplication
also in other contexts,
whenever you find it convenient.

In addition to that, you indicate multiplication
in the usual way by an asterisk (`*`).
Division is indicated
by a slash (`/`) or `per`.
Division of numbers can also be indicated by the vertical dash (`|`).
Examples:

10cm 15cm 1m = 15 liters 7 * furlongs per fortnight = 0.0011641667 m/s 1|2 meter = 0.5 m

The multiplication operator `*` has the same
precedence as `/` and `per`;
these operators are evaluated from left to right.

Multiplication using juxtaposition has higher
precedence than `*` and division.
Thus, `m/s s/day` does not mean `(m/s)*(s/day)`
but `m/(s*s)/day = m/(s*s*day)`,
which has dimension of length per time cubed.
Similarly, `1/2 meter` means
`1/(2 meter) = .5/meter`, which is
probably not what you would intend.

The division operator `|` has precedence
over both kinds of multiplication,
so you can write 'half a meter' as `1|2 meter`.
This operator can only be applied to numbers.

Sums are written with
the plus (`+`) and minus (`-`).
Examples:

2 hours + 23 minutes - 32 seconds = 8548 seconds 12 ft + 3 in = 373.38 cm 2 btu + 450 ft lbf = 2720.2298 J

The quantities which are added together must have identical dimensions.
For example, `12 printerspoint + 4 heredium` results in this message:

Sum of non-conformable values: 0.0042175176 m 20186.726 m^2.

Plus and minus can be used as unary operators. Minus as a unary operator negates the numerical value of its operand.

Exponents are specified using the operator `^` or `**`.
The exponent must be a number.
As usual, `x^(1/n)` means the `n`-th root of `x`,
and `x^(-n)` means `1/(x^n)`:

cm^3 = 0.00026417205 gallon 100 ft**3 = 2831.6847 liters acre^(1/2) = 208.71074 feet (400 W/m^2 / stefanboltzmann)^0.25 = 289.80881 K 2^-0.5 = 0.70710678

An exponent `n` or `1/n` where `n` is not an integer
can only be applied to a number.
You can take the `n`-th root of non-numeric quantity
only if that quantity is an `n`-th power:

foot^pi = Non-numeric base, 0.3048 m, for exponent 3.1415927. hectare**(1/3) = 10000 m^2 is not a cube.

An exponent like `2^3^2` is evaluated **right to left**.

The operators `^` and `**` have precedence over multiplication and division,
so `100 ft**3` is 100 cubic feet, not `(100 ft)**3`.
On the other hand, they have a lower priority than prefixing and `|`,
so `centimeter^3` means cubic centimeter,
but `centi meter^3` is 1/100 of a cubic meter.
The square root of two thirds can be written as `2|3^1|2`.

**Abbreviation.** You may concatenate a one-digit exponent,
`2` through `9`, directly after a unit name.
In this way you abbreviate `foot^3` to `foot3`
and `sec^2` to `sec2`.

But beware: `$ 2` means two dollars, but `$2` means one dollar squared.

`Units` provides a number of functions
that you can use in your computation.
You invoke a function in the usual way, by writing its name
followed by the argument in parentheses.
Some of them are built into the program, and some are defined in the units data base.

The built-in functions include
`sin`, `cos`, `tan`,
their inverses
`asin`, `acos`, `atan`,
and:

ln natural logarithm log base-10 logarithm log2 base-2 logarithm exp exponential sqrt square root, sqrt(x) = x^(1/2) cuberoot cube root, cuberoot(x) = x^(1/3)

The argument of `sin`, `cos`, and `tan` must be a number or an angle.
They return a number.

The argument of `asin`, `acos`, `atan`,
`ln`, `log`, `log2`, and `exp`
must be a number.
The first three return an angle and the remaining return a number.

The argument of `sqrt` and `cuberoot`
must be a number, or a quantity that is a square or a cube.

circlearea area of circle with given radius pH converts pH value to moles per liter tempF converts temperature Fahrenheit to temperature Kelvin wiregauge converts wire gauge to wire thickness

Most of them are used to handle nonlinear scales, as explained under Nonlinear meaures.

By preceding a function's name with a tilde (`~`)
you obtain an inverse of that function:

circlearea(5cm) = 78.539816 cm^2 ~circlearea(78.539816 cm^2) = 5 cm pH(8) = 1.0E-8 mol/liter ~pH(1.0E-8 mol/liter) = 8 tempF(97) = 309.26111 K ~tempF(309.26111 K) = 96.999998 wiregauge(11) = 2.3048468 mm ~wiregauge(2.3048468 mm) = 11

The following table summarizes all operators in the order of precedence.

prefix concatenated exponent number division | (left to right) unary + - exponent ^ ** (right to left) multiplication by juxtaposition (left to right) multiplication and division * / per (left to right) sum + - (left to right)

A plus and minus is treated as unary only if it comes
first in the expression or follows any of the operators
`^`, `**`, `*`, `/`,
`per`, `+`, or `-`.
Thus, `5 -2` is interpreted as '5 minus 2',
and not as '5 times -2'.

Parentheses can be applied in the usual way to indicate the order of evaluation.

The syntax of expressions is defined as follows.
Phrases and symbols in quotes represent themselves,
`|` means 'or', `?` means optional occurrence,
and `*` zero or more occurrences.

expr=term(('+' | '-')term)* | ('/' | 'per')productterm=product(('*' | '/' | 'per')product)*product=factorfactor*factor=unary(('^' | '**')unary)*unary= ('+' | '-')?primaryprimary=unitname|numexpr|bfunc'('expr')' | '~'?dfunc'('expr')' | '('expr')'numexpr=number('|'number)*number=mantissaexponent?mantissa= '.'digits|digits('.'digits?)?exponent= ('e' | 'E')sign?digitsunitname= unit name with optional prefix, suffix, and / or one-digit exponentbfunc= built-in function name: sqrt, cuberoot, sin, cos, etc.dfunc= defined function name

Names of syntactic elements shown above in italics may appear in error messages that you receive if you happen to enter an incorrect expression. For example:

You have: 1|m After '1|': expected number. You have: cm^per $ After 'cm^': expected unary. You have: 3 m+*lbf After '3 m+': expected term.

Spaces are in principle ignored, but they are often required
in multiplication by juxtaposition.
For example, writing `newtonmeter` will result in the message
`Unit 'newtonmeter' is unknown`; you need a space
in the product `newton meter`.

To avoid ambiguity, a space is also required before a number
that follows another number.
Thus, an error will be indicated after `1.2` in `1.2.3`.

Multiplication by juxtaposition may also result in another ambiguity.
As `e` is a small unit of charge, an expression like `3e+2C`
can be regarded as meaning `(3e+2)*C` or `(3*e)+(2*C)`.
This ambiguity is resolved by always including as much as possible in a number.

In the Overview, it was shown how you specify the result
by entering a unit name at `You` `want`.
In fact, you can enter there any expression specifying
a quantity with the same dimension as the expression at `You have`:

You have: 10 gallons You want: 20 cm * circlearea(5cm) 10 gallons = 24.09868 * 20 cm * circlearea(5cm)

This tells you that you can almost fit 10 gallons of liquid into 24 cans of diameter 10 cm and 20 cm tall. However:

You have: 10 gallons You want: circlearea(5cm) Conformability error 10 gallons = 0.037854118 m^3 circlearea(5cm) = 0.0078539816 m^2

Some units, like radian and steradian, are treated as dimensionless and equal to 1
if it is necessary for conversion.
For example, power is equal to torque times angular velocity.
The dimension of expression at `You have` below is `kg m^2 radian/s^3`,
and the dimension of `watt` is `kg m^2/s^3`
The computation is made possible by treating radian as dimensionless:

You have: (14 ft lbf) (12 radians/sec) You want: watts (14 ft lbf) (12 radians/sec) = 227.77742 watts

Note that dimensionless units are not treated as dimensionless
in other contexts.
They cannot be used as exponents so for example, `meter^radian` is not allowed.

You can also enter at `You` `want`
an expression with dimension that is an inverse of that at `You have`:

You have: 8 liters per 100 km You want: miles per gallon reciprocal conversion 1 / 8 liters per 100 km = 29.401823 miles per gallon

Here, `You have` has the dimension of volume divided by length,
while the dimension of `You` `want` is length divided by volume.
This is indicated by the message `reciprocal conversion`,
and by showing the result as equal to the inverse of `You have`.

You may enter at `You` `want` the name of a function,
without argument.
This will apply the function's inverse to the quantity from `You have`:

You have: 30 cm^2 You want: circlearea 30 cm^2 = circlearea(0.030901936 m) You have: 300 K You want: tempF 300 K = tempF(80.33)Of course,

You have: 30 cm You want: circlearea Argument 0.3 m of function ~circlearea is not conformable to 1 m^2.

If you leave `You` `want` field empty, you obtain
the quantity from `You have` reduced to primitive units:

You have: 7 mph You want: 3.12928 m / s

You have: 2 m You want: ft;in;1|8 in 2 m = 6 ft + 6 in + 5.9212598 * 1|8 inNote that you are not limited to unit names, but can use expressions like

Ending the unit list with '`;`' separates the integer and fractional parts
of the last coefficient:

You have: 2 m You want: ft;in;1|8 in; 2 m = 6 ft + 6 in + 5|8 in + 0.9212598 * 1|8 inEnding the unit list with '

You have: 2 m You want: ft;in;1|8 in;; 2 m = 6 ft + 6 in + 6|8 in (rounded up to nearest 1|8 in)Each unit on the list must be conformable with the first one on the list, and with the one you entered at

You have: meter You want: ft;kg Invalid unit list. Conformability error: ft = 0.3048 m kg = 1 kg You have: meter You want: lb;oz Conformability error meter = m lb = 0.45359237 kgOf course you should list the units in a decreasing order; otherwise, the result may not be very useful:

You have: 3 kg You want: oz;lb 3 kg = 105 oz + 0.051367866 lbA unit list such as

cup;1|2 cup;1|3 cup;1|4 cup;tbsp;tsp;1|2 tsp;1|4 tspcan be tedious to enter.

hms hours, minutes, seconds dms angle: degrees, minutes, seconds time years, days, hours, minutes and seconds usvol US cooking volume: cups and smallerUsing these shorthands, or unit list aliases, you can do the following conversions:

You have: anomalisticyear You want: time 1 year + 25 min + 3.4653216 sec You have: 1|6 cup You want: usvol 2 tbsp + 2 tspYou cannot combine a unit list alias with other units: it must appear alone at

Some measures cannot be expressed as the product of a number
and a measurement unit.
Such measures are called *nonlinear*.

An example of nonlinear measure is the `pH` value used to express
the concentration of certain substance in a solution.
It is a negative logarithmic measure:
a tenfold increase of concentration decreases the `pH` value by one.
You convert between `pH` values and concentration
using the function `pH`
mentioned under Functions:

You have: pH(6) You want: micromol/gallon pH(6) = 3.7854118 micromol/gallon

For conversion in the opposite direction,
you use the inverse of `pH`, as described
under Specifying result:

You have: 0.17 micromol/cm^3 You want: pH 0.17 micromol/cm^3 = pH(3.7695511)

Other example of nonlinear measures are different "gauges".
They express the thickness of a wire, plate, or screw, by a number that is not obviously
related to the familiar units of length.
(Use the `Search` button on `gauge`
to find them all.)
Again, they are handled by functions that convert the gauge to units of length:

You have: wiregauge(11) You want: inches wiregauge(11) = 0.090742002 inches You have: 1mm You want: wiregauge 1mm = wiregauge(18.201919)

The most common example of nonlinear measure is the temperature indicated by a thermometer,
or *absolute temperature*:
you cannot really say that it becomes two times warmer when the thermometer goes
from 20°F to 40°F.
Absolute temperature is expressed relative to an origin;
such measure is called *affine*.
To handle absolute temperatures, `Units` provides functions
such as `tempC` and `tempF` that convert them
to degrees Kelvin.
(Other `temp` functions can be found using the `Search` button.)
The following shows how you use these functions to convert
absolute temperatures:

You have: tempC(36) You want: tempF tempC(36) = tempF(96.8)

meaning that 36°C on a thermometer is the same as 96.8°F.

You can think of `pH(6)`, `wiregauge(11)`, `tempC(36)`, or `tempF(96.8)`
not as functions but as readings on the scale `pH`, `tempC`, or `tempF`,
used to measure some physical quantity.
You can read the examples above as:
'what is `0.17 micromol/cm^3` on the `pH` scale?', or
'what is `1 mm` on the `wiregauge` scale?', or
'what is the `tempF` reading corresponding to `36` on `tempC` scale?'

Note that absolute temperature is not the same as *temperature difference*,
in spite of their units having the same names.
The latter **is** a linear quantity.
Degrees Celsius and degrees Fahrenheit for measuring temperature difference
are defined as linear units
`degC` and `degF`.
They are converted to each other in the usual way:

You have: 36 degC You want: degF 36 degC = 64.8 degF

Some units have different values in different locations. The localization feature accomodates this by allowing the units database to specify region-dependent definitions.

In the database, the US units that differ from their British counterparts have names
starting with `us`: `uston`, `usgallon`, etc..
The corresponding British units are: `brton`, `brgallon`, etc..
When using `Units`, you have a possibility to specify
`en_US` or `en_GB` as 'locale'.
Each of them activates a portion of the database that defines
short aliases for these names.
Thus, specifying `en_US` as locale activates these aliases:

ton = uston gallon = usgallon etc.while

ton = brton gallon = brgallon etc.

You can specify locale in the property list or in a command option.

The US Survey foot,
yard, and mile can be obtained by using the `US` prefix.
These units differ slightly from the international length units.
They were in general use until 1959, and are still used
for geographic surveys.
The acre is officially defined in terms of the US Survey foot.
If you want an acre
defined according to the international foot, use `intacre`. The
difference between these units is
about 4 parts per million.
The British also used a slightly different length measure before 1959.
These can be obtained with the prefix `UK`.

The units data base is defined by a *units data file*.
A default units file, called `units.dat`, is packaged in the JAR file together
with the program.
(You can extract it from there using the `jar` tool of Java.)

If you want to add your own units, you can write your own units file.
See how to do it under Writing units file.
If you place that file in your home directory
under the name `units.dat`,
it will be read after the default units file.

You may also supply one or more own unit files and access them
using the property list
or command option.
In each case, you specify the order in which `Units` will read them.
If a unit with the same name is defined more than once,
`Units` will use the last definition that it encounters.

If you want, you may run `Units` from command line.
It imitates then almost exactly
the behavior of GNU Units.
(The differences are listed under What is different.)

To use the command line interface,
you need to
download the Java archive (JAR) file
that contains the executable classes and the data file.
You can save the JAR in any directory of your choice, and give it any name
compatible with your file system.
The following assumes that you saved the JAR file under the name
` jarfile`.
It also assumes that you have a Java Runtime Environment (JRE) version 1.5.0
or later that is invoked by typing

java -jarjarfile-i or java -jarjarfileoptions

at your shell prompt. The program will print something like this:

2192 units, 71 prefixes, 32 nonlinear units You have:

At `You have` prompt, type the expression you want to evaluate.
Next, `Units` will print `You` `want`.
There you tell how you want your result, in the same way as in the graphical interface.
See under Expressions
and Specifying result.
As an example, suppose
you just want to convert ten meters to feet.
Your dialog will look like this:

You have: 10 meters You want: feet * 32.8084 / 0.03048

The answer is displayed in two ways.
The first line,
which is marked with a `*` to indicate multiplication,
says that the quantity at `You have`
is `32.8084` times the quantity at `You` `want`.
The second line,
marked with a `/` to indicate division, gives
the inverse of that number.
In this case, it tells you that 1 foot is equal to about
0.03 dekameters (dekameter = 10 meters).
It also tells you that 1/32.8 is about .03.

`Units` prints the inverse because sometimes it is a
more convenient number.
For example, if you try to convert grains to pounds, you will see the following:

You have: grains You want: pounds * 0.00014285714 / 7000

From the second line of the output you can immediately see that a grain is equal to a seven thousandth of a pound. This is not so obvious from the first line of the output.

If you find the output format confusing, try using the
`-v` ('verbose') option, which gives:

You have: 10 meters You want: feet 10 meters = 32.8084 feet 10 meters = (1 / 0.03048) feet

You can suppress printing of the inverse using the `-`1 ('one line') option.
Using both `-v` and `-`1 produces the same output
as the graphical interface:

You have: 5 yards * (4 feet + 3 in) * 7 in * 1 kg/liter You want: pounds 5 yards * (4 feet + 3 in) * 7 in * 1 kg/liter = 2321.5398 pounds

If you request a conversion between units which measure reciprocal
dimensions, `Units` will display the conversion results with an extra
note indicating that reciprocal conversion has been done:

You have: 6 ohms You want: siemens reciprocal conversion * 0.16666667 / 6Again, you may use the

You have: 6 ohms You want: siemens reciprocal conversion 1 / 6 ohms = 0.16666667 siemens 1 / 6 ohms = (1 / 6) siemens

When you specify compact output with `-c`,
you obtain only the conversion factors, without indentation:

You have: meter You want: yard 1.0936133 0.9144

When you specify compact output and perform conversion to mixed units, you obtain only the conversion factors separated by semicolons. Note that unlike the case of regular output, zeros are included in this output list:

You have: meter You want: yard;ft;in 1;0;3.3700787

If you only want to find the reduced form or definition of a unit,
simply press return at `You` `want` prompt.
For example:

You have: 7 mph You want: 3.12928 m/s You have: jansky You want: Definition: jansky = fluxunit = 1e-26 W/m^2 Hz = 1e-26 kg / s^2

The definition is shown if you entered a unit name at `You have` prompt.
The example indicates that `jansky` is defined as
equal to `fluxunit` which in turn is defined to be a certain combination
of watts, meters, and hertz.
The fully reduced form appears on the far right.

If you type `?` at
`You` `want` prompt, the program will display a list of named
units which are conformable with the unit that you entered at
`You have` prompt.
Note that conformable unit
combinations will not appear on this list.

Typing `help` at either prompt displays a short help message.
You can also type `help` followed by a unit name.
This opens a window on the units file at the point where that unit
is defined.
You can read the definition and comments that may
give more details or historical information about the unit.

Typing `search` followed by some text
at either prompt displays a list of all units
whose names contain that text as a substring,
along with their definitions.
This may help in the case where you aren't sure of the right unit name.

To end the session, you type `quit` at either prompt,
or press the Enter (Return) key at `You have` prompt.

You can use `Units` to perform computations non-interactively
from the command line.
To do this, type

java -jarjarfile[options]you-have[you-want]

at your shell prompt. (You will usually need quotes to protect the expressions from interpretation by the shell.) For example, if you type

java -jarthe program will printjarfile"2 liters" "quarts"

* 2.1133764 / 0.47317647and then exit.

If you omit *you-want*, `Units` will print out
definition of the specified unit.

The following options allow you to use alternative units file(s), check your units file, or change the output format:

`-C`- Check that all units and prefixes defined in the units data file reduce
to primitive units. Print a list of all units that
cannot be reduced. Also display some other diagnostics about
suspicious definitions in the units data file.
Note that only
definitions active in the current locale are checked.
This option may be specified with
`-v`to help find unit definitions that cause endless loops. Any other options and arguments are ignored. `-c`- compact: give compact output featuring only the conversion factor(s).
This option overrides the
`-v`option. `-e`*charset*

Assume that input and output in the interactive mode is encoded using the character set named. It must be one of the character sets available at your Java installation. See Unicode support for more detail.*charset*`-f`*filename*

Load the units file. You should specify full path as*filename*.*filename*

Empty string as(*filename*`-f ""`) means the`units.dat`file supplied with the program. This enables you to use the supplied file plus a personal units file. Up to 25 units files may be specified on the command line. The files will be read in the order they appear in the command.`-g`*fontname*

Use fontin the window diplayed in response to*fontname*`help`,`?`, and`search`. It must be one of the fonts available at your Java installation. See Unicode support for more detail.`-h`- help: print out a summary of the options for
`Units`. `-i`- interactive: use interactive prompts (rather than graphic interface).
`-l`*locale*

Use the specified*locale*. If locale is not specified in this way,`Units`uses`en_US`. It does not attempt to obtain locale from the system.`-q`- quiet: suppress prompting of the user for units and the display of statistics about the number of units loaded.
`-r`- round: in conversion to a sum of units, round the last term of the result to an integer. Overrides a semicolon appearing at the end of unit list.
`-s`- strict: suppress conversion of units to their reciprocal units. For
example,
`Units`will normally convert hertz to seconds because these units are reciprocals of each other. The strict option requires that units be strictly conformable to perform a conversion, and will give an error if you attempt to convert hertz to seconds. `-`1- one-line: give only one line of output (the forward conversion).
Do not print the reverse conversion.
Note that if
`Units`performs a reciprocal conversion, it will still print the "reciprocal conversion" line. `-t`- terse: give terse output.
This option can be used when calling
`Units`from another program so that the output is easy to parse. It is equivalent to specifying`-csq`1. `-v`- verbose: give slightly more verbose output.
`-V`- Print program version number.

The Java imitation is not an exact port of the original GNU units. The following is a (most likely incomplete) list of differences.

- Long options are not supported.
- Invocation of
`Units`from command line does not return a success / failure code. - Options
`--oldstar`and`--newstar`that control the precedence of the multiplication operator`*`are not supported.

The operator`*`has the same precedence as`/`and`per`. - Options
`-m`and`-p`are not supported.

The binary operator`-`in unit expressions always means subtraction. - Option
`-o`is not supported.

Numbers are printed in the format produced by Java conversion from*Double*to*String*. - Option
`--compact`is specified as`-c`, and option`--check`as`-C`. - Rounding of the last element of unit list can be alternatively specified by a double semicolon at the end of unit list.
- Option
`-S`(`--show-factor`) is not supported. A not very elegant way around is to enclose the unit in parentheses, producing`5 * (1|2 cup)`instead of`5 * 1|2 cup`. - Option
`-e`has a different meaning, and there are two new options,`-g`and`-l`. - Environment variables are not supported.
They are replaced by Properties and options.

In particular, the program does not obtain locale from the system. If you want to use locale other than the default (`en_US`), you have to specify it by means of a`-l`option, or a Property. - Readline is not supported.
- Interactive use from command line is terminated by typing 'quit' at either prompt, or by pressing return at 'You have:' prompt.
- Error diagnostics are different.
- The personal unit file in home directory is named
`units.dat`instead of`.units.dat`. (Windows does not accept file names starting with a dot.) The 'home directory' is defined as the one returned by Java method`System.getProperty("user.home")`. - The commands
`!utf8`and`!endutf8`in the units file are ignored. See Unicode support.

You can supply some parameters to `Units`
by setting up a *Property list*.
It is a file named `units.opt`, placed in
the same directory as the JAR file.
It may look like this:

GUIFONT = Lucida ENCODING = Cp850 LOCALE = en_GB UNITSFILE = ; c:\\Java\\gnu\\units\\my.dat

`GUIFONT =`*fontname*

specifies the font to be used by the graphical interface. It must be one of the fonts available at your Java installation. If you do not specify this property,`Units`will use the`Monospaced`font. See Unicode support for more detail.`ENCODING =`*charset*

tells`Units`to assume that input and output in the interactive mode is encoded using the character set named. It must be one of the character sets available at your Java installation. If you do not specify this property,*charset*`Units`will assume the default encoding used by the Java Virtual Machine. See Unicode support for more detail.`LOCALE =`*locale*

specifies the locale to be used instead of the default`en_US`.`UNITSFILE =`*filelist*

specifies the unit definition file(s) to be used. Theis a list of file names separated by semicolons. Each file must be specified by full path. An empty name indicates the*filelist*`units.dat`file supplied with`Units`. The files will be read in the order they appear in the list. Notice that each backslash character (`\`) in the example is escaped by another backslash. In general, the property file must have the format specified for method`load`of class`Properties`in Java API Specification.

The options `-e`, `-f`, `-g`, and `-l`
specified on the command line
override settings from the Property list.

Starting with release 1.7.0_51, Java blocks unsigned applets.
For this reason, you can no longer embed `Units` as an applet in your web page.

The units data base is defined by a units data file.
A default units file, called `units.dat`, is packaged in the JAR file together
with the program.
This section tells you how to write your own units file that you can
use together with, or instead of, the default file,
as described under Adding own units.

The file has to use the UTF-8 character encoding. Since the ASCII characters appear the same in all encodings, you do not need to worry about UTF-8 as long as your definitions use only these characters.

Each definition occupies one line, possibly continued
by the backslash character (`\`) that
appears as the last character.

A line starting with `!` is a command.
See Defining locale
and Including file.
Non-command lines may start with white space (blanks or tab characters).

Comments start with a `#` character, which can appear
anywhere in a line.
Following `#`, the comment extends to the end of the line.

Empty lines are ignored.

A unit is specified on a single line by giving its name followed by at least one blank, followed by the definition.

A unit name must not contain any of the characters `+`
`-` `*` `/` `|` `^`
`(` `)` `;` `#`.
It cannot begin with a digit, underscore, tilde,
decimal point, or comma.
It cannot end with an underscore, decimal point, or comma.

If a name ends in a digit
other than zero or one, the digit must be preceded by a string beginning with an underscore,
and afterwards consisting only of digits, decimal points, or commas.
For example, `NO_2`,
`foo_2,1` or `foo_3.14` would be valid names
but `foo2` or `foo_a2` would be invalid.

The definition is either an expression, defining the unit in terms
of other units, or `!` indicating a primitive unit,
or `!dimensionless` indicating a dimensionless primitive unit.

Be careful to define
new units in terms of old ones so that a reduction leads to the
primitive units.
You can check this using the `-C` option.
See under Checking your definitions.

Here is an example of a short units file that defines some basic units:

m ! # The meter is a primitive unit sec ! # The second is a primitive unit rad !dimensionless # A dimensionless primitive unit micro- 1e-6 # Define a prefix minute 60 sec # A minute is 60 seconds hour 60 min # An hour is 60 minutes inch 0.0254 m # Inch defined in terms of meters ft 12 inches # The foot defined in terms of inches mile 5280 ft # And the mile

A unit which ends with a `-` character is a prefix. If a prefix
definition contains any `/` characters, be sure they are protected
by parentheses. If you define `half- 1/2` then `halfmeter`
would be equivalent to `1 / 2 meter`.

Here is an example of function definition:

tempF(x) [1;K] (x+(-32)) degF + stdtemp ; (tempF+(-stdtemp))/degF + 32

The definition begins with the function name followed immediately (with no spaces) by the name of the parameter in parentheses. Both names must follow the same rules as unit names.

Next, in brackets, is a specification of the units required as arguments by
the function and its inverse.
In the example above, the
`tempF` function requires an input argument conformable with `1`.
The inverse function requires an input argument conformable
with `K`.
Note that this is also the dimension of function's result.

Next come the expressions to compute the function and its inverse,
separated by a semicolon.
In the example above, the
`tempF` function is computed as

tempF(x) = (x+(-32)) degF + stdtemp

The inverse has the name of the function as its parameter. In our example, the inverse is

~tempF(tempF) = (tempF+(-stdtemp))/degF + 32

This inverse definition takes an absolute temperature as its argument
and converts it to the Fahrenheit temperature. The inverse can be
omitted by leaving out the `;` character, but then conversions to
the unit will be impossible.

If you wish to make synonyms for nonlinear units, you still need to define
both the forward and inverse functions.
So to create a synonym for `tempF` you could write

fahrenheit(x) [1;K] tempF(x); ~tempF(fahrenheit)

The example below is a function to compute the area of a circle. Note that this definition requires a length as input and produces an area as output, as indicated by the specification in brackets.

circlearea(r) [m;m^2] pi r^2 ; sqrt(circlearea/pi)

Empty or omitted argument specification means that `Units`
will not check dimension of the argument you supply.
Anything compatible with the specified computation will work.
For example:

square(x) x^2 ; sqrt(square) square(5) = 25 square(2m) = 4 m^2

Some functions cannot be computed using an expression. You have then a possibility to define such a function by a piecewise linear approximation. You provide a table that lists values of the function for selected values of the argument. The values for other arguments are computed by linear interpolation.

An example of piecewise linear function is:

zincgauge[in] 1 0.002, 10 0.02, 15 0.04, 19 0.06, 23 0.1

In this example, `zincgauge` is the name of the function.
The unit in square brackets applies to the result.
Tha argument is always a number.
No spaces can appear before the
`]` character, so a definition like `foo[kg meters]` is
illegal; instead write `foo[kg*meters]`.

The definition is a list of pairs optionally separated by commas.
Each pair defines the value of the function at one point.
The first item in each pair is the function argument; the second item is the
value of the function at that argument (in the units specified in brackets).
In this example,
you define `zincgauge` at five points.
We have thus
`zincgauge(1) = 0.002 in`.

Definitions like this may be more readable if written using continuation characters as

zincgauge[in] \ 1 0.002 \ 10 0.02 \ 15 0.04 \ 19 0.06 \ 23 0.1

If you define a piecewise linear function that is not strictly
monotone, the inverse will not be well defined.
In such a case, `Units` will return the smallest
inverse.

Unit list aliases are treated differently from unit definitions,
because they are a data entry shorthand rather than a true definition
for a new unit.
A unit list alias definition begins with `!unitlist`
and includes the alias and the definition;
for example, the aliases included in the standard units data file are:

!unitlist hms hr;min;sec !unitlist time year;day;hr;min;sec !unitlist dms deg;arcmin;arcsec !unitlist ftin ft;in;1|8 in !unitlist usvol cup;3|4 cup;2|3 cup;1|2 cup;1|3 cup;1|4 cup;\ tbsp;tsp;1|2 tsp;1|4 tsp;1|8 tsp

Unit list aliases are only for unit lists,
so the definition must include a '`;`'.
Unit list aliases can never be combined with units or
other unit list aliases, so the definition of `time` shown above could
not have been shortened to `year;day;hms`.
As usual, be sure to run `Units` with option `-C`
to ensure that the units listed in unit list aliases
are conformable.

A locale region in the units file
begins with `!locale` followed by the name of the locale.
The locale region is terminated by `!endlocale`.
The following example shows how to define a couple of units in a locale.

!locale en_GB ton brton gallon brgallon !endlocale

A file can be included by giving the command `!include` followed by
full path to the file.

You are recommended to check the new or modified units file
by invoking `Units` from command line with option `-C`.
Of course, the file must be made available to `Units`
as described under Adding own units.

The option will check that the definitions are correct,
and that all units reduce to primitive ones.
If you created a loop in the units definitions, `Units` will
hang when invoked with the `-C` option.
You will need to
use the combined `-Cv` option which prints out each unit as it
checks them.
The program will still hang, but the last unit printed
will be the unit which caused the infinite loop.

If the inverse of a function is omitted, the
`-C` option will display a warning.
It is up to you to
calculate and enter the correct inverse function to obtain proper
conversions.
The `-C` option tests the inverse at one point
and prints an error if it is not valid there, but this is not a guarantee
that your inverse is correct.

The `-C` option will print a warning if a
non-monotone piecewise linear function is encountered.

`Units` works internally with double-byte Unicode characters.

The unit data files use the UTF-8 encoding. This enables you to use Unicode characters in unit names. However, you can not always access them.

The graphical interface of `Units` can display all characters
available in its font.
Those not available are shown as empty rectangles.
The default font is `Monospaced`.
It is a so-called *logical font*, or a font family, with different versions
depending on the locale.
It usually contains all the national characters and much more,
but far from all of Unicode.
You may specify another font by using the property `GUIFONT`,
or the command option `-g`.

You can enter into the `Units` window all chracters available
at your keyboard, but there is no facility to enter any other
Unicode characters.

The treatment of Unicode characters at the command interface
depends on the operating system and the Java installation.
The operating system
may use character encoding different from the default
set up for Java Virtual Machine (JVM).
As the result, names such as `ångström`
typed in the command window are not recognized as unit names.
If you encounter this problem, and know the encoding used by the system,
you can identify the encoding to `Units`
with the help of the property `ENCODING`
or command option `-e`.
(In Windows XP, you can find the encoding using the command `chcp`.
In one case investigated by the author, the encoding was `Cp437`,
while the JVM default was `Cp1252`.)

The `units.dat` file supplied with `Units`
contains commands `!utf8` and `!endutf8`.
This is so because it is taken unchanged from `GNU units`.
The commands enclose the portions of file that use non-ASCII characters
so they can be skipped in environments that do not support UTF-8.
Because Java always supports the UTF-8 encoding for input files,
the commands are ignored in `Units`.

The program documented here is a Java development of
`GNU Units 1.89e`, a program
written in C by Adrian Mariano (adrian@cam.cornell.edu).
The file `units.dat` containing the units data base
was created by Adrian Mariano, and is maintained by him.
The package contains the latest version obtained from
`GNU Units` repository.

GNU Units copyright © 1996, 1997, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2010, 2011 by Free Software Foundation, Inc. Java version copyright © 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 by Roman Redziejowski.

The program is free software: you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

The program 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 General Public License for more details.

This Web page copyright © 2012 by Roman Redziejowski. The author gives unlimited permission to copy, translate and/or distribute it document, with or without modifications, as long as this notice is preserved, and information is provided about any changes.

Substantial parts of this text
have been taken, directly or modified, from the manual `Unit Conversion`,
edition 1.89g, written by Adrian Mariano,
copyright © 1996, 1997, 1999, 2000, 2001, 2002, 2003, 2004,
2005, 2006, 2007, 2011 by Free Software Foundation, Inc.,
under a written prmission contained in that document.