Skip to content

UDUNITS

UDUNITS is a package for managing physical quantities with units.

UDUNITS is available as a module on Apocrita. The package provides a library with C API and a command line utility. These are supported by a provided database of units, including conversion formulas between units.

Using UDUNITS

To access the default installed version of the UDUNITS package, load the udunits module:

module load udunits

On Apocrita, only version 2 of the UDUNITS package is available. The documentation details inconsistencies with version 1 of the API.

Using the command line utility

The command line utility udunits2 allows you to query a units database. Actions include displaying the definition of a unit in terms of SI base units or converting between units:

$ # See the definition of the W (Watt) unit
$ udunits2 -H W -W ''
    m²·kg·s⁻³
$ # Convert 1.3 miles (mi) to metres (m)
$ udunits2 -H 1.3mi -W m
    1.3 mi = 2092.15 m
    x/m = 1609.34*(x/mi)

Without further options, udunits2 queries the bundled units database. An alternative database may be given as an option to the command line. Usage of the utility is given with the -h option:

$ udunits2 -h
Usage:
    udunits2 -h
    udunits2 [-A|-L|-U] [-r] [-H have] [-W want] [XML_file]

where:
    -A         Use ASCII encoding (default).
    -L         Use ISO-8859-1 (ISO Latin-1) encoding.
    -U         Use UTF-8 encoding.
    -h         Help.  Print this message.
    -r         Reveal any problems in the database.
    -H have    Use "have" unit for conversion. Default is reply to prompt.
    -W want    Use "want" unit for conversion. Empty string requests
               definition of "have" unit. Default is reply to prompt.
    XML_file   XML database file. Default is "/share/apps/centos7/udunits/[...]/share/udunits/udunits2.xml".

Using the C API

The UDUNITS package provides the C header file udunits2.h. The module on Apocrita sets the environment variable C_INCLUDE_PATH to have the path containing this header file.

To compile a program using the UDUNITS library the necessary linker flags should be provided:

gcc ... ${LDFLAGS} -l udunits2

Documentation

Documentation of the UDUNITS package is installed on Apocrita in Info format:

info udunits2
info udunits2lib

References