Some unit conversions of interest are nonlinear; for example, temperature conversions between the Fahrenheit and Celsius scales cannot be done by simply multiplying by conversion factors.
When you give a linear unit definition such as ‘inch 2.54 cm’ you are providing information that units uses to convert values in inches into primitive units of meters. For nonlinear units, you give a functional definition that provides the same information.
Nonlinear units are represented using a functional notation. It is best to regard this notation not as a function call but as a way of adding units to a number, much the same way that writing a linear unit name after a number adds units to that number. Internally, nonlinear units are defined by a pair of functions that convert to and from linear units in the data file, so that an eventual conversion to primitive units is possible.
Here is an example nonlinear unit definition:
tempF(x) units=[1;K] (x+(-32)) degF + stdtemp ; \
(tempF+(-stdtemp))/degF + 32
A nonlinear unit definition comprises a unit name, a dummy parameter name, two functions, and two corresponding units. The functions tell units how to convert to and from the new unit. In order to produce valid results, the arguments of these functions need to have the correct dimensions. To facilitate error checking, you may optionally indicate units for these arguments.
The definition begins with the unit name followed immediately (with no spaces) by a ‘(’ character. In parentheses is the name of the parameter. Next is an optional specification of the units required by the functions in this definition. In the example above, the ‘tempF’ function requires an input argument conformable with ‘1’. For normal nonlinear units definitions the forward function will always take a dimensionless argument. The inverse function requires an input argument conformable with ‘K’. In general the inverse function will need units that match the quantity measured by your nonlinear unit. The purpose of the expression in brackets to enable units to perform error checking on function arguments, and also to assign units to range and domain specifications, which are described later.
Next the function definitions appear. In the example above, the ‘tempF’ function is defined by
tempF(x) = (x+(-32)) degF + stdtemp
This gives a rule for converting ‘x’ in the units ‘tempF’ to linear units of absolute temperature, which makes it possible to convert from tempF to other units.
In order to make conversions to Fahrenheit possible, you must give a rule for the inverse conversions. The inverse will be ‘x(tempF)’ and its definition appears after a ‘;’ character. In our example, the inverse is
x(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 the inverse is omitted then the --check option will display a warning. It is up to you to calculate and enter the correct inverse function to obtain proper conversions. The --check 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.
If you wish to make synonyms for nonlinear units, you still need to define both the forward and inverse functions. Inverse functions can be obtained using the ‘~’ operator. So to create a synonym for ‘tempF’ you could write
fahrenheit(x) units=[1;K] tempF(x); ~tempF(fahrenheit)
You may define a function whose range and domain do not cover all of the real numbers. In this case units can handle errors better if you specify an appropriate range and domain. You specify the range and domain as shown below.
baume(d) units=[1;g/cm^3] domain=[0,130.5] range=[1,10] \
(145/(145-d)) g/cm^3 ; (baume+-g/cm^3) 145 / baume
In this example the domain is specified after the ‘domain=’ with the endpoints given in brackets. One of the end points can be omitted to get an interval that goes to infinity. So the range could be specified as nonnegative by writing ‘range=[0,]’. Both the range and domain are optional and can appear independently and in any order along with the ‘units’ specification. The values in the range and domain are attached to the units given in the ‘units’ specification. If you don't specify the units then the parameter inputs are reduced to primitive units for the numeric comparison to the values you give in the range or domain. In this case you should only use ‘range’ or ‘domain’ if the endpoints are zero and infinity.
Specifying the range and domain allows units to perform better error checking and give more helpful error messages when you invoke nonlinear units conversions outside of their bounds. It also enables the -c option to find a point in the domain to use for its point check of your inverse definition.
You may occasionally wish to define a function that operates on units. This can be done using a nonlinear unit definition. For example, the definition below provides conversion between radius and the area of a circle. This definition requires a length as input and produces an area as output, as indicated by the ‘units=’ specification. Specifying the range as the nonnegative numbers can prevent cryptic error messages.
circlearea(r) units=[m;m^2] range=[0,] pi r^2 ; sqrt(circlearea/pi)
Sometimes you may be interested in a piecewise linear unit such as many wire gauges. Piecewise linear units can be defined by specifying conversions to linear units on a list of points. Conversion at other points will be done by linear interpolation. A partial definition of zinc gauge 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 piecewise linear unit. The definition of such a unit is indicated by the embedded ‘[’ character. After the bracket, you should indicate the units to be attached to the numbers in the table. No spaces can appear before the ‘]’ character, so a definition like ‘foo[kg meters]’ is illegal; instead write ‘foo[kg*meters]’. The definition of the unit consists of a list of pairs optionally separated by commas. This list defines a function for converting from the piecewise linear unit to linear units. 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, we define ‘zincgauge’ at five points. For example, we set ‘zincgauge(1)’ equal to ‘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
With the preceding definition, the following conversion can be performed:
You have: zincgauge(10)
You want: in
* 0.02
/ 50
You have: .01 inch
You want: zincgauge
5
If you define a piecewise linear unit that is not strictly monotonic, then the inverse will not be well defined. If the inverse is requested for such a unit, units will return the smallest inverse. The --check option will print a warning if a non-monotonic piecewise linear unit is encountered.