UDUNITS

Overview

UDUNITS is a C library providing arithmetic manipulation of units and conversion of numeric values between compatible units. The package contains an extensive unit database, which is in XML format and user-extendable. The package also contains a command-line utility for investigating units and converting values.

Restrictions on use

There are no restrictions on access to the UDUNTIS libraries on CSF. The software is released under a license given at the start of the online documentation and at $UDUNITSDIR/COPYRIGHT text file on the CSF. All usage must adhere to this license.

Set up procedure

We now recommend loading modulefiles within your jobscript so that you have a full record of how the job was run. See the example jobscript below for how to do this. Alternatively, you may load modulefiles on the login node and let the job inherit these settings.

Load one of the following modulefiles to set up your environment:

module load libs/gcc/udunits/2.2.26

Compiling an UDUNITS-capable application

You will mostly use the UDUNITS installation on CSF3 when compiling your own software. This allows you to add UDUNITS functionality to your own apps. There are some tools you can also run to process existing data files (see below).

The modulefiles will set an environment variable named ${UDUNITSDIR} which can then be used in your compilation process (e.g., in a Makefile or directly on the command-line) to access the header and library files:

• To inform the compiler of the header file directory use:

  gcc -I${UDUNITSDIR}/include ....

• To inform the compiler of the library files use:

  gcc ... -L${UDUNITSDIR}/lib -ludunits2

• In a Makefile ensure you use ${UDUNITSDIR} rather than $UDUNITSDIR.

An example compilation command could be

gcc -I${UDUNITSDIR}/include example_units.c -o example_units -L${UDUNITSDIR}/lib -ludunits2

Running an UDUNITS-capable application

You must load the UDUNITS modulefile before running your UDUNITS-capable application (unless you have statically linked your code against the UDUNITS libraries).

Please do not run UDUNITS-capable applications on the login node. Jobs should be submitted to the compute nodes via batch.

Serial batch job submission

Create a batch submission script (which will load the modulefile in the jobscript), for example:

#!/bin/bash --login
#$ -cwd             # Job will run from the current directory
                    # NO -V line - we load modulefiles in the jobscript

# Load the serial (non-MPI) modulefile
module load libs/gcc/udunits/2.2.26

# Run my application I compiled earlier
./myunitsapp arg1 ...

Submit the jobscript using:

qsub scriptname

where scriptname is the name of your jobscript.

UDUNITS Tools

The UDUNITS bin directory is added to your path so that you can access the udunits2 tool. Use ls ${UDUNITSBIN} to see all binary tools:

# UDUNITS tools - must be used in batch jobs, as above
udunits2

Further info

See the UDUNITS website for full documentation.

Updates

None.