Writing Transforms for IVE

The "transform" subroutine library is the method for users to link their own code into IVE. The transform routines handle such things as array index to physical coordinate transformations and the calculation of user-derived fields. Users need not supply IVE with a complete set of customized transform routines; IVE will use the default version of any transform subroutine that does not appear in the user's package of customized routines. Customized transform packages may be loaded automatically by setting the environment variable 'IVETRANSFILE' to the full path name of the file containing the customized transforms. Transform routines can also be loaded at any time during an IVE session using the command TRANSFORM_FILE .

The following is the list of standard transform subroutines that may be called during an IVE session. The default IVE transform package is available in both C and Fortran. To download the default transform package, click HERE.

IVE Transform Subroutines

NEW_FILE

This routine is called every time a new file is read in. IVE passes the routine the id of the open netCDF file. The routine can then read any data or attributes off the netCDF file. Quantities that are read by the default version of `new_file' include the global attributes and the data in coordinate variables. Customized versions of `new_file' might read additional data fields such as an array of bottom topography or auxillary data to be used in calculating derived fields.

NEW_FIELD

This routine is called every time a new field is specified. Before calling `new_field' IVE reads in the variable and its attributes IVE passes the routine the name of the field, the data values and the dimensions of the data array. This routine can be used to get and store the physical coordinate values for use by the coordinate transform routines. This routine also can be used to reorder the data array and dimensions.

INDEX_2_PHYS

This routine is used to convert from array indices to physical coordinates. IVE provides a vector containing the array indices The routine should return the corresponding physical coordinates.

PHYS_2_INDEX

This routine is used to convert from physical coordinates to array indices. IVE provides a vector containing the physical coordinates. The routine should return the corresponding array indices. A negative index indicates that this data point should be assigned the missing value (e.g. a point under the terrain) .

HORIZ_TER

This routine is used to provide IVE with an array of terrain heights for a horizontal cross-section. If you have no terrain, this routine should return an array of zeroes.

VERT_TER

This routine is used to provide IVE with an array of terrain heights for a vertical cross-section. If you have no terrain, this routine should return an array of zeroes.

PHYS_2_LONLAT

This routine is used to convert from physical coordinates to longitude-latitude coordinates for the purposes of drawing maps. IVE provides a vector containing the physical coordinates. This routine should return the corresponding longitude-latitude coordinates.

LONLAT_2_PHYS

This routine is used to convert from longitude-latitude coordinates to physical coordinates for the purposes of drawing maps. IVE provides a vector containing the longitude-latitude coordinates. This routine should return the corresponding physical coordinates.

DEFAULT_MAP

This routine returns the map settings when the default map is specified in IVE.

DATA_SLICER_1D

This routine returns the computational points at which a 1d slice should be taken. This is used if IVE cannot figure out on its own which points to use. Normally, IVE will try to space points evenly in computational space if possible. If data_slicer_1d is not available, IVE will evenly space the points in physical space.

DATA_SLICER_2D

This routine returns the computational points at which a 2d slice should be taken. This is used if IVE cannot figure out on its own which points to use. Normally, IVE will try to space points evenly in computational space if possible. If data_slicer_2d is not available, IVE will evenly space the points in physical space.

DATA_SLICER_3D

This routine returns the computational points at which a 3d slice should be taken. This is used if IVE cannot figure out on its own which points to use. Normally, IVE will try to space points evenly in computational space if possible. If data_slicer_3d is not available, IVE will evenly space the points in physical space.

CALC_FIELD

This routine is used to give the user the ability to compute their own derived fields. IVE provides the name of the field requested by the user. The routine computes the derived field and returns it.

HEADING

This routine allows the users to change the main headings on a plot.

FILE_COORDINATE

This routine allows the users to change the current value of the file coordinate used for reading a variable over multiple files (see the MULTIPLE_READ command and the section "Splitting data into multiple files" in IVE Data Format for more details).

Miscellaneous

Users may include any other routines they need as part of the computations for the transform routines. If you start the name of the routine, or any common blocks, with "t_", they will not conflict with the name of any IVE external.

Calling IVE subroutines from the transforms

You may need to call IVE subroutines as part of the transforms. The following is a list of useful routines (Fortran callable):

function getvar(var_name, ndims, dims, stagger, phmin, phmax, missing, data_units, display_units, dim_names, flag)
This routine returns a pointer to the memory location where the specified variable is stored. If it is not currently in memory and it exists in the netCDF file, it is read into memory. If the variable does not exist in the netCDF, getvar tries to calculate it, which may involve a call to calc_field. The newly computed variable will NOT have a button in the main IVE widget. Users should be careful when using this routine in calc_field not to end up in an infinite loop of calc_field calls. Several other pieces of information about the variable are also returned in the arrays ndims, stagger, min, max, missing, data_units, display_units and dim_names.


var_name	character	input	variable name
ndims	integer	output	number of dimensions
dims	integer	output	an array of dimensions
stagger	real	output	an array with the grid staggering for each dimension
phmin	real	output	an array of minimums in physical space for each dimension
phmax	real	output	an array of maximums in physical space for each dimension
missing	real	output	missing value
data_units	character	output	data units
display_units	character	output	desired units for data display
dim_names	character	output	an array containing the names of the dimensions for this variable. Can be either existing names from the netCDF file or new names.
flag	logical	in/out	on input .true. -> write error message if variable is not found or computed. On output .true. -> new memory was allocated for this variable.

function addvar(var_name, button_name, ndims, dims, stagger, phmin, phmax, missing, data_units, display_units, dim_names, flag)
This routine is similiar to getvar. The difference is that a new button with the name "button_name" is created if necessary, for the variable "var_name". The calling sequence is the same as getvar, with the additional parameter button_name:

button_name character input name of the button for this field.

function getrarr(name, value, size, error)
This routine gets the named IVE real array. The parameters are:


name	character	input	name of IVE array
value	real	output	the array to receive the values
size	integer	input	the size of array "value"
error	integer	output	if non-zero => could not get array

The corresponding routine setrarr stores named IVE real array variables. The following are IVE real arrays that may be of interest:


plmin	domain minimum in physical coordinates (4)
plmax	domain maximum in physical coordinates (4)
phmin	minimum physical coordinates for current field (4)
phmax	maximum physical coordinates for current field (4)
stag	grid staggering for current field (4)

There is also getaarr and setaarr which gets and stores IVE character arrays. The following are IVE character arrays that may be of interest:


domain_units	the units of the domain physical coord. (4)
domain_units_display	the current units used to display phys. coord. (4)
domain_units_display_orig	the original units used to display phys. coord. (4)

getlvar(name, value, error)
This routine gets the named IVE logical variables. The parameters are:

name character input name of IVE variable

value logical output the value of the variable

error integer output if non-zero => could not get array

The corresponding routine setlvar stores the named IVE logical variable. The following are IVE logical variables that may be of interest:
read_from_nc
Whether the last variable read in was read from the netCDF file or was already in memory (or was a calculated field)
make_help_widget(string)
This routine pops up a window containing the specified character string. This is used to display error messages to the user.

Programming considerations for writing transforms in FORTRAN

Some of the routines above (for example read_var) deal with pointers to arrays. Standard FORTRAN does not have a concept of pointers. The Sun and DEC FORTRAN compilers have extensions that allow primitive pointer manipulations. The problem is that FORTRAN wants to deal with the arrays and variables themselves, not the pointers. Getting to the object a pointer reference is called "dereferencing a pointer". The method for dereferencing a pointer "p" is to use the built in function "%val(p)". However, this function can only be used in a subroutine or function call, i.e.

    call junk(%val(p))

Subroutine "junk" can then work with the object to which p points. If "p" points to an array, you should also pass to "junk" the array dimensions for use by junk. As an example of this procedure, examine at the FORTRAN version of the default transform discussed below and see how a pointer to a 1D array is dereferenced in the function "t_val".

Examples

There are currently two examples of transforms. The first example consists of the default transforms. The default transforms are sufficiently flexible to handle several types of netcdf files. The second example consists of the transforms to handle real time Numerical Product grids from NMC.

EXAMPLE 1: THE DEFAULT TRANSFORMS

default.c and default.f are C and Fortran versions of the default transforms. The default transforms and IVE can handle the following types of netCDF files:

A plain netCDF file with four dimensional arrays (C/netCDF style A[nt,nz,ny,nx], Fortran style A(nx,ny,nz,nt)). In this case, the physical coordinates are the array indices. The domain limits are set to be the largest value of each dimension of the four dimensional arrays, and the sliders will show the limits x: 1 to nx, y: 1 to ny, z: 1 to nz, t: 1 to nt. If any dimension has a value of 1, the slider for that dimension will not appear.
A netCDF file with four dimensional arrays and one dimensional variables with the same name as the dimensions. In this case the "dimension" variables are used to define the physical coordinates. These "dimension variables" may be irregularly spaced. The domain limits are set to be the values corresponding to the largest value of each dimension of the four dimensional array. The file can also contain a mix of dimensions matching this method and method 1 above.

A netCDF file with the following attributes defined ([] => optional):

    Global: domxmin, domxmax [, x_units, x_display_units]
        domymin, domymax [, y_units, y_display_units]
        domzmin, domzmax [, z_units, z_display_units]
        domtmin, domtmax [, t_units, t_display_units]


     Per Field: xmin, xmax  [, units, display_units]
        ymin, ymax  [, units, display_units]
        zmin, zmax  [, units, display_units]
        tmin, tmax  [, units, display_units]
                [missing_data]

The default transforms use linear interpolation to compute transformations between physical space and array indices. Let xminB and xmaxB denote the values of the "per field" attributes xmin and xmax of the FORTRAN array B. Then B(i,?,?,?) will be plotted at the x-location

xminB + (i-1)*(xmaxB-xminB)/(nx-1)

with respect to the interval (domxmin, domxmax). The grid intervals, delta_x, delta_y, delta_z and delta_t must be uniform in order for the data to be displayed without distortion.

It is possible to mix the techniques for domain specification discussed in examples 1-3 to describe the physical range of different coordinates. For example, one could specify dom*min and dom*max for x,y, and z and provide a one dimensional array listing discrete values for t (i.e., specify t according to the preceding method #2).

The following is an example of the header section of this third type of netcdf file:

      
netcdf steep_c_hst {
dimensions:
    nx = 801 ;
    ny = 1 ;
    nz = 80 ;
    nxp1 = 802 ;
    time = UNLIMITED ; // (8 currently)

variables:
    float time(time) ;
        time:units = "s" ;
    float theta(time, nz, ny, nx) ;
        theta:units = "degK" ;
        theta:display_units = "degK" ;
        theta:xmin = 0.f ;
        theta:zmin = 50.f ;
        theta:xmax = 160000.f ;
        theta:zmax = 7950.f ;
        theta:missing_data = 9.9999994e+31f ;
    float p(time, nz, ny, nx) ;
        p:units = "Pa" ;
        p:display_units = "millibars" ;
        p:xmin = 0.f ;
        p:zmin = 50.f ;
        p:xmax = 160000.f ;
        p:zmax = 7950.f ;
        p:missing_data = 9.9999994e+31f ;
    float u(time, nz, ny, nxp1) ;
        u:units = "m/s" ;
        u:display_units = "m/s" ;
        u:xmin = -100.f ;
        u:zmin = 50.f ;
        u:xmax = 160100.f ;
        u:zmax = 7950.f ;
        u:missing_data = 9.9999994e+31f ;
    float w(time, nz, ny, nx) ;
        w:units = "m/s" ;
        w:display_units = "cm/s" ;
        w:xmin = 0.f ;
        w:zmin = 0.f ;
        w:xmax = 160000.f ;
        w:zmax = 7900.f ;
        w:missing_data = 9.9999994e+31f ;

// global attributes:
        :domxmin = 0.f ;
        :domzmin = 0.f ;
        :domxmax = 160000.f ;
        :domzmax = 8000.f ;
        :x_units = "m" ;
        :z_units = "m" ;
        :x_display_units = "km" ;
        :z_display_units = "km" ;

data:

 time = 300 , 600 , 900 , 1200 , 1500 , 1800 , 2100 , 2400 ;
}

In this example, the sliders will show the limits x : 0 to 160 (km), y : no slider, z: 0 to 8 (km), t:300 to 2400 (sec). The y-coordinate slider is omitted because ny=1 (in which case domymin and domymax, although they may be specified in the netcdf file, are irrelevant). The t-coordinate slider is specified according to the technique in example two.

Note also that the "dimensions" section of the preceding netcdf header contains the additional parameter nxp1, which is used to increase the first (FORTRAN) dimension of the variable "u" by 1 with respect to the other variables. As evident from the "per variable" values of xmin and xmax, the data in the array "u" are staggered 100 m along the x-coordinate with respect to the data in the arrays "theta", "p" and "w". The "w" array is also staggered 50 m along the z-coordinate with respect to the data in the arrays "theta", "p" and "u".

EXAMPLE 2: TRANSFORMS FOR NMC GRIDS

nps.c is the transform used to handle the real time (HDS/NPS) grids from NMC. The extra features in these transforms are:

The forecast time (frtime) dimension/variable is not sorted. The transform sorts frtime, returns the correct limits for that dimension, and reorders the variables read from the netCDF so they are in time increasing order.
Some fields are 3 dimensional: longitude, latitude and frtime. IVE requires fields to have the following dimensions: x, y, z, t. The transforms supply the missing vertical coordinate with a dimension of one, which tells IVE that it is missing.
Interpolations in the vertical are done in log P rather than linear P.

back to index