Udunits/IDL Interface

David W. Pierce
Scripps Institution of Oceanography

-------------------------------------------

Version 0.2 Released 26 April, 1999

What is it?

If you use the Udunits package from Unidata, and the IDL data processing package from Research Systems Inc., then you might want to use the two together. This bit of code is a native IDL interface to the udunits package, so you can call your familiar Udunits routines directly from IDL.

Caveats

At the moment, there are significant limitations to the interface:

With those caveats in mind, I personally find it quite useful to be able to access the udunits functionality in a seamless way from IDL, and you might too.

Download the source for the Udunits/IDL Interface, version 0.2.

back to top

-------------------------------------------

Installation Guide

Step 1. Set up the Makefile

In the Makefile, you must set the following variables:

Unless you happen to be on a Dec Alpha, you will likely have to change a few compilation options as well. There are vague hints on how to do this in the "Advanced Development Guide" manual from RSI. The key point seems to be that you want to produce a shared (.so) file. On the Dec, you give the linker the option "-shared" to accomplish this. It might be different on your machine.

Step 2. Run "make"

This should make one .so file for each of the functions. For example, utistime.so, utscan.so, etc.

Step 3. Edit "load_udu.pro"

You must edit the routine "load_udu.pro" to reflect the location where the resulting .so files can be found. Just set variable 'basedir' to the proper directory location. You can either have IDL use "load_udu.pro" as its .rc (initial startup) file, which will automatically make the routines available every time you use IDL, or run "load_udu" as needed on a case by case basis. Note: because of the way IDL works, you must run load_udu BEFORE compiling any routines that use the udunits routines! Otherwise, IDL will not recognize the calls as valid function calls.

back to top

-------------------------------------------

User's Guide

The routines map between two structures: the udunit's C-code structure "utUnit", and an IDL structure called "UDUNITS." You should probably consider the IDL structure UDUNITS to be an opaque structure in case the udunits library changes at some point, but here is the IDL structure's definition at the moment:

{ UDUNITS, origin:0.0, factor:0.0, has_origin:0, power:intarr(10) }

(In fact, there seems little use in porting the utHasOrigin routine when you can just check the has_origin member).

For calendar functions, the following "UTCAL" structure is used by the routines:

{ UTCAL, year:0, month:0, day:0, hour:0, minute:0, second:0.0 }

utinit

Usage: err = utinit()

Initializes the udunits package. This must be called before any other udunits routines. Returns 0 on success. You must have the UDUNITS_PATH environmental variable set to the location of the udunits data file ("udunits.dat") for this call to succeed.

utscan

Usage: err = utscan( string_in, units_struct_out )

Converts a textual representation of units, in IDL string variable 'string_in', into an IDL "UDUNITS" structure (as described above), which is left in the named variable 'units_struct_out. Returns 0 on success.

utcalendar

Usage: err = utcalendar( val_to_convert, units_struct_in, utcal_struct_out )

Takes input value 'val_to_convert', which should be a double precision number, and uses information in the IDL "UDUNITS" structure 'units_struct_in' to convert to a "UTCAL" structure output. The UTCAL structure is described above. The UDUNITS structure must have both an origin and units of time for this call to succeed. Returns 0 on success.

utconvert

Usage: err = utconvert( units_struct_from_in, units_struct_to_in, udconvert_struct_out )

Determines the slope and intercept required to convert FROM the input "UDUNITS" structure 'units_struct_from_in' TO the input "UDUNITS" structure 'units_struct_to_in'. The slope and intercept are returned in output IDL structure 'udconvert_struct_out', which has form: { UDCONVERT, slope:0.0, intercept:0.0 }. The units in the 'from' and 'to' structures must be compatable, i.e., their quotient must be dimensionless. Returns 0 on success.

utistime

Usage: is_time = utistime( units_struct_in )

Returns 1 if the UDUNITS structure passed in 'units_struct_in' has units of time, and to 0 otherwise. This ignores whether or not the units has an origin.

utinvcalendar

Usage: err = utinvcalendar( udcal_struct_in, units_struct_in, timeval_out )

Converts a calendar date, described by the UDCAL structure passed in via udcal_struct_in, and making use of the UDUNITS structure passed in via 'units_struct_in', into a double precision output value put into named variable 'timeval_out'. Returns 0 on success.

back to top

-------------------------------------------

Copyright

This code, referred to as the "udunits/IDL interface version 0.2", is hereby placed in the public domain by its author, David W. Pierce. This code may be copied, modified, and/or redisitributed in any manner whatsoever with no restrictions. THIS CODE COMES "AS IS", WITH NO WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

The udunits package and IDL each have their own copyrights, which are entirely separate from the copyright on this bit of interface code. This copyright on the "udunits/IDL interface version 0.2" says nothing about the copyrights on those other packages.

END OF TERMS AND CONDITIONS

back to top

-------------------------------------------

Revision History

26 April, 1999: 0.2: Fixed bug in utconvert. Was incorrectly using float instead of double in one place. Resulted in bad conversions when the value did not fit in a float.

26 March, 1999: 0.1: Initial released version.

back to top

-------------------------------------------

Back to David Pierce's home page.

Last modified March 26, 1999