libipc.gex - Support Functions for GrADS Inter-process Communication

- NAME
- SYNOPSIS

- GrADS Commands:
- GrADS Functions:

- DESCRIPTION
- COMMANDS PROVIDED

- ipc_open FILENAME MODE
- ipc_save EXPR [FILENAME]
- ipc_close [MODE]
- ipc_verb [ON|OFF]
- ipc_error

- FUNCTIONS PROVIDED

- define void = ipc_save ( EXPR [, FILENAME] )
- define `var` = ipc_load ( [FILENAME] )
- define `var` = ipc_pipe ( [COMMAND] )

- EXAMPLES
- TRANSFER FILE FORMAT

- 1st record: The dimension environment record.
- 2nd record: This contains the gridded data.
- 3rd record. The i-dimension coordinate variable
- 4th record. The j-dimension coordinate variable

- AUTHOR
- COPYRIGHT

# NAME

libipc.gex - Support Functions for GrADS Inter-process Communication

# SYNOPSIS

### GrADS Commands:

  ipc_open FILENAME MODE

  ipc_save EXPR [FILENAME]

  ipc_close [MODE]

  ipc_verb [ON|OFF]

  ipc_error

### GrADS Functions:

  define `var` = ipc_save ( EXPR [, FILENAME] )

  define `var` = ipc_load ( [FILENAME] )

  define `var` = ipc_pipe ( [COMMAND] )

# DESCRIPTION

This library of GrADS extensions implements functions to enable GrADS inter-proceess communication. The primary use of these functions is to facilitate the interface of GrADS to other applications by means of bi-directional pipes (e.g., Perl, Python, IDL, Octave, etc.). The current implementation provides functions and commands for exporting and importing gridded fields from and into GrADS. These functions can also be used as a convenient alternative to `LATS` or `fwrite` for saving and retrieving gridded variables to and from disk files.

Data is exchanged by means of a stream interface: either external files or through STDIN and STDOUT, the prefered method when interfacing with bi-directional pipes. The actual file format borrows from the GrADS classic User Defined Functions (UDFs), with extensions to allow exporting/importing of timeseries (more generally, a collection of 2D slices). See TRANSFER FILE FORMAT below for a description of this format.

# COMMANDS PROVIDED

## ipc_open FILENAME MODE

This command opens a file for exporting or importing gridded fields from or into GrADS. On iput,

FILENAME is the name of the file to open; specify ``-'' for selecting standard input/output instead of a disk file.

MODE - it can be either w for exporting gridded data from GrADS or r for importing gridded data into GrADS. All data is exchanged using the native binary format.

IMPORTANT. When standard output is selected, the verbose mode is automatically turned off to avoid corrupting the output stream.

## ipc_save EXPR [FILENAME]

This command evaluates the GrADS expression EXPR and saves the resulting gridded field to a file or to standard output. On input,

EXPR is a gridded GrADS expression

FILENAME is an optional parameter specifying a file name to export the data to, or ``-'' for exporting the data to standard output. When FILENAME is specified as a disk file, the file is opened, written to and closed upon completion. Therefore, FILENAME should not be specified in the presence of a looping dimension (animation sequence), or else the file will be overwritten for each instance of the looping dimension. In such cases, explicity open and close the file before and after exporting to it.

## ipc_close [MODE]

This command closes the streams used for exporting/importing gridded data. It has no effect when the streams are standard input/output. On input,

MODE is set to w the file used for exporting data is closed; when MODE is set to r the file used for importing data is closed. If omitted, both streams are closed.

## ipc_verb [ON|OFF]

This command toggles verbose ON/OFF; do not use it when using STDIN/STDOUT as transfer streams. If not argument is provided it will toggle the verbose mode ON or OFF.

## ipc_error

This command reprints the last IPC error message, returning its error code. This is useful when exchanging data using bi-directional pipes.

# FUNCTIONS PROVIDED

## define void = ipc_save ( EXPR [, FILENAME] )

This function is similar to the ipc_save command above. It is provided as a function for symmetry with the imp function below, and to allow exporting a timeseries to a single file using the GrADS define command. For saving a timeseries, setup the dimension environment in GrADS as usual for an animation sequence and issue a `define` command such as

            define void = ipc_save(sqrt(ua*ua+va*va))

Remember not to specify a disk FILENAMNE as an argument to ipc_save() when intending to save a timeseries to a single file, or else your file will contain only the last 2D field in the sequence.

## define `var` = ipc_load ( [FILENAME] )

This function imports gridded data from the currently open stream or from file FILENAME, if specified. Do not specify FILENAMNE when intending to import a timeseries from a single file. In such cases, explicity open and close the file before and after exporting to it.

## define `var` = ipc_pipe ( [COMMAND] )

This function implements an interface to external processes by means of an uni-directional pipe. This is accomplished my means of the C function `popen()`, and the command being executed is assumed to write out a sequential (Fortran) binary file, where the first 4 bytes contain an integer with the size of the remaining data to be read.

Although extremely useful, this function is not intented for the casual user. When issuing a `ipc_pipe()`, the dimension environment should match exactly the size of the data being read.

# EXAMPLES

Saving/loading simple variables with only 2 varying dimensions (say, fixed time), specifying a transfer file:

            ga-> ipc_save ps ps.bin
            ga-> define saved = ipc_load("ps.bin")
            ga-> display ps-saved

The same example, using open and close:

            ga-> ipc_open ps.bin w
            ga-> ipc_save ps
            ga-> ipc_close

            ga-> ipc_open ps.bin r
            ga-> display ps-ipc_load()
            ga-> ipc_close

Saving a timeseries:

            ga-> set lon 0 360
            ga-> set lat -90 90
            ga-> set lev 300
            ga-> set t 1 5
            ga-> ipc_open zg.bin w
            ga-> define void = ipc_save(zg)
            ga-> ipc_close

Retrieving the same time series:

            ga-> set t 1 5
            ga-> ipc_open zg.bin r
            ga-> define saved = ipc_load()
            ga-> display saved
            ga-> ipc_close

# TRANSFER FILE FORMAT

The format of the transfer file borrows from GrADS traditional UDF transfer files, but it has been simplified a bit since only gridded fields need to be exchanged. It has also been slightly extended to allow the saving/loading of a collection of 2D fields to a single file, as is the case when dealing with timeseries data. In particular, the first header record with 20 float point numbers used in traditional UDF files has been eliminated.

Since the argument is always an expression, GrADS will evaluate the expression and write the result to the transfer file. Currently only gridded data is supported, but support of station data is planned for future releases. Several records will be written to the file for each value of the looping dimension (usually time).

## 1st record: The dimension environment record.

This record contains 20 values, all floating point. Note that some of the values are essentially integer, but for convenience they are written as a floating point array. Appropriate care should be taken in converting these values back to integer. The description of each one of these 20 float point numbers follow:

                     1:  Undefined value for the grid
                     2:  i dimension (idim).  Dimensions are:
                         -1 - None
                          0 - X dimension (lon)
                          1 - Y dimension (lat)
                          2 - Z dimension (lev)
                          3 - T dimension (time)
                     3:  j dimension (jdim).  Note:  if idim and
                         jdim are -1, the grid is a single value.
                         If jdim is -1, the grid is a 1-D grid.
                     4:  number of elements in the i direction (isiz)
                     5:  number of elements in the j direction (jsiz)
                         Array is dimensioned (isiz,jsiz).
                     6:  i direction linear flag.  If 0, the
                         i dimension has non-linear scaling.
                     7:  j dimension linear flag.
                     8:  istrt.  This is the world coordinate value
                         of the first i dimension, ONLY if the i dimension
                         has linear scaling and the i dimension is not
                         time.
                     9:  iincr.  Increment in the i dimension of the
                         world coordinate.  ONLY if the i dimension has
                         linear scaling.
                     10: jstrt.  World coordinate of the first j
                         dimension, only if the j dimension has linear
                         scaling, and the j dimension is not time.
                     11: jincr.  World coordinate increment for j
                         dimension.
                     12: If one of the dimensions is time, values
                         12 to 16 are defined as the start time
                         12 is the start year.
                     13: start month
                     14: start day
                     15: start hour
                     16: start minute
                     17: Values 17 and 18 contain the time increment
                         for the time dimension.  17 contains the
                         increment in minutes.
                     18: increment in months.  (GrADS handles all
                         increments in terms of minutes and months).
                     19,20: reserved

## 2nd record: This contains the gridded data.

It has isiz*jsiz floating point numbers.

## 3rd record. The i-dimension coordinate variable

Whether or not the i or j dimension scaling is non-linear, the world coordinate values at each integral `i(j)` dimension value is written. Thus, isiz float point numbers will be written. Notice that this is a departure from the classic UDF format.

## 4th record. The j-dimension coordinate variable

This record has the j dimension world coordinate values; it contains jsiz floating point numbers.

Unlike the classic UDF file format, the 3rd or 4th records are always written. Note that the time dimension is ALWAYS linear as currently implemented in GrADS.

# AUTHOR

Arlindo da Silva (dasilva@opengrads.org), based on code fragments from GrADS.

# COPYRIGHT

Copyright (C) 2007 Arlindo da Silva; portions derived from GrADS source code Copyright (C) 1988-2007 by Brian Doty and the Institute of Global Environment and Society (IGES).

This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

libipc.gex - Support Functions for GrADS Inter-process Communication