DEOS Technical Note #13
Version 2
Copyright © 2004-2012 Delaware Environmental Observing System
Published: August 6th 2004
| Revision History | ||
|---|---|---|
| Revision 1.1 | 2004/08/06 | GEQ |
| Initial version | ||
| Revision 1.2 | 2004/08/30 | GEQ |
| Revised for rrpm real index arrays. | ||
| Revision 1.3 | 2004/09/08 | GEQ |
| Added statement of missing data. | ||
| Revision 1.4 | 2004/09/21 | GEQ |
| Added error condition to interface, specified possible error values and clarified output coordinate specifications. | ||
| Revision 1.5 | 2004/10/12 | GEQ |
| Modified error conditions for block use. Added data convention statement for rrpm. | ||
| Revision 1.6 | 2005/03/23 | GEQ |
| Modified error conditions to the more general status conditions after adding extract program use. | ||
| Revision 1.7 | 2005/03/25 | GEQ |
| Added -22 and -23 to error conditions. | ||
| Revision 1.8 | 2005/03/29 | GEQ |
| Added -10 to error conditions. Made the status condition message section it's own main section. | ||
| Revision 1.9 | 2005/04/11 | GEQ |
| Added -11 and -12 to error conditions. | ||
| Revision 1.10 | 2006/03/27 | GEQ |
| Added interface for calibrated product. | ||
| Revision 1.11 | 2006/03/30 | GEQ |
| Added revised interface for Z bias and exponent values. Now providing file value and station value. | ||
| Revision 1.12 | 2006/03/31 | GEQ |
| Added -102 and -103 to error conditions. | ||
| Revision 2.1 | 2006/09/26 | GEQ |
| Incremented version number of this document to 2. | ||
| Revision 2.1 | 2006/12/11 | GEQ |
| Added -24 to error conditions. | ||
| Revision 2.2 | 2006/12/13 | GEQ |
| Added -3 to error conditions. | ||
| Revision 2.3 | 2007/01/03 | GEQ |
| Added dfe to -102 error condition. Added -104 condition. | ||
| Revision 2.1.6 | 2008/02/13 | GEQ |
| Revised compiler versions to their current values. | ||
| Revision 2.1.7 | 2008/03/21 | GEQ |
| Added ifgen interface. | ||
Table of Contents
This document summarizes the interfaces between the C++ and Fortran components of the SMARTS programs.
The following are general issues surrounding the discussions in the following sections. and Fortran components of SMARTS .
SMARTS is built using version 4.1.2 of the GNU Fortran compiler.
The numerically intensive parts of the program are constructed using Fortran.
SMARTS is built using version 4.1.2 of the Gnu Compiler System.
The non-numerically intensive parts of the SMARTS programs are constructed using C++.
In order for the numerical processing to be undertaken using the Fortran derived components, data must be exchanged between the C++ driving component and the Fortran numerical processing component. This is accomplished using combinations of the following structures to hide most of the details of the data being transferred.
In each case, details are given of the C++ class and the corresponding Fortran derived type.
Member Names
The names of internal data members can differ between the two languages. The types must correspond as written as well as the sizes of the items, but the names do not have to match.
Missing Data
For the array data, values that are ≥ zero shall be considered to be valid data, any value < zero will be considered missing data and thus be ignored.
This class is designed to store a single index of an array to be passed as a separate command line argument. However, it may be used to store any run-time integer data as required.
class IntegerArray {
public:
int order;
int x_start;
int y_start;
int x_size;
int y_size;
int * data;
int padding[20];
};
 | This is the class definition statement. The class name in C++ and the derived type name in Fortran do not have to be the same. |
 | This statement indicates that the member values described below are directly accessible. |
 | The rank of the data array contained in the class is given by |
 | The X value of the starting cell of the data array. |
 | The Y value of the starting cell of the data array. |
 | The size of the array in the X direction. |
 | The size of the array in the Y direction. |
 | An integer array of rank |
 | An array containing the Fortran array information metadata. |
The equivalent derived type in Fortran would be:
type f_integer_array
sequence
integer :: order
integer :: x_start
integer :: y_start
integer :: x_size
integer :: y_size
integer,dimension(:), pointer :: data
integer :: padding(20)
end type
| This is the derived type definition statement. The class name in C++ and the derived type name in Fortran do not have to be the same. |
| This statement guarantees that the elements are stored in the order specified. |
| The rank of the data array contained in the class is given by |
| The X value of the starting cell of the data array. |
| The Y value of the starting cell of the data array. |
| The size of the array in the X direction. |
| The size of the array in the Y direction. |
| An integer array of rank |
| An array containing the Fortran array information metadata. |
The order value must always have a meaningful value. The other options, including the data
array, may be provided, if they are not, then a negative value shall be placed in that variable. An unallocated data
array must be accompanied by a value of order of zero.
This class is designed to store a single floating-point data array. However, it may be used to store any run-time integer data as required. The class also contains data to allow an entire array to be specified, if desired.
class FloatArray {
public:
int order;
int x_start;
int y_start;
int x_size;
int y_size;
float * data;
int padding[20];
};
| This is the class definition statement. The class name in C++ and the derived type name in Fortran do not have to be the same. |
| This statement indicates that the member values described below are directly accessible. |
| The rank of the data array contained in the class is given by |
| The X value of the starting cell of the data array. |
| The Y value of the starting cell of the data array. |
| The size of the array in the X direction. |
| The size of the array in the Y direction. |
| An floating-point array of rank |
| An array containing the Fortran array information metadata. |
The equivalent derived type in Fortran would be:
type f_real_array
sequence
integer :: order
integer :: x_start
integer :: y_start
integer :: x_size
integer :: y_size
real,dimension(:), pointer :: data
integer :: padding(20)
end type
| This is the derived type definition statement. The class name in C++ and the derived type name in Fortran do not have to be the same. |
| This statement guarantees that the elements are stored in the order specified. |
| The rank of the three arrays contained in the class is given by |
| The X value of the starting cell of the data array. |
| The Y value of the starting cell of the data array. |
| The size of the array in the X direction. |
| The size of the array in the Y direction. |
| An floating-point array of rank |
| An array containing the Fortran array information metadata. |
The order value must always have a meaningful value. The other options, including the data
array, may be provided, if they are not, then a negative value shall be placed in that variable. An unallocated data
array must be accompanied by a value of order of zero.
This section describes the method whereby integer user or system settings for the product are transferred from C++ to the Fortran processing portion.
class IntegerOptions {
public:
int order;
int option[N_I];
};
| This is the class definition statement. The class name in C++ and the derived type name in Fortran do not have to be the same. |
| This statement indicates that the member values described below are directly accessible. |
| The rank of the option array set to N_I. |
| An array of rank |
The equivalent derived type in Fortran would be:
type f_integer_options
sequence
integer :: order
integer,dimension(N_I) :: option
end type
| This is the derived type definition statement. The class name in C++ and the derived type name in Fortran do not have to be the same. |
| This statement guarantees that the elements are stored in the order specified. |
| The rank of the integer options array set to N_I. |
| An array of rank Even if there is only one option, the derived type will use an embedded array of length one. |
This section describes the method whereby floating point user or system settings for the product are transferred from C++ to the Fortran processing portion.
class FloatOptions {
public:
int order;
float option[N_F];
};
| This is the class definition statement. The class name in C++ and the derived type name in Fortran do not have to be the same. |
| This statement indicates that the member values described below are directly accessible. |
| The rank of the option array set to N_F. |
| An array of rank |
The equivalent derived type in Fortran would be:
type f_real_options
sequence
integer :: order
real,dimension(N_F) :: option
end type
| This is the derived type definition statement. The class name in C++ and the derived type name in Fortran do not have to be the same. |
| This statement guarantees that the elements are stored in the order specified. |
| The rank of the integer options array set to N_F. |
| An array of rank Even if there is only one option, the derived type will use an embedded array of length one. |
This section describes the possible values of the status flag and associated message passed as an integer as the last argument on a call to a SMARTS processing subroutine call.
The status codes are also used in other areas of SMARTS but adhere to this table.
In general, a value of zero indicates successful completion, a value less than zero indicates a fatal error condition, and a value greater than zero indicates a non-fatal but warning condition.[1]
Table 1. Interpretation of Status Codes
| Value | Generator | Description |
|---|---|---|
| -104 | dfe Program | The option specifying the team name is invalid. |
| -103 | rrpm Program | The option specifying the calibration method is invalid. |
| -102 | ifgen, rrpm or dfe Programs | The option specifying the field type is invalid. |
| -101 | rrpm Program | The option specifying the procedure for combining values for a given cell occurring in multiple radars is invalid. |
| -24 | Input Data Check | One or more alphabetic data type names provided were invalid. |
| -23 | General Data Error | No records were returned from the database where one or more were expected. |
| -22 | Input Data Check | The stream name provided as input data is invalid. |
| -21 | Input Data Check | The station name provided as input data is invalid. |
| -20 | Input Data Check | The network name provided as input data is invalid. |
| -12 | File Open | When opening the file requested, one of more "bad" bits was set. |
| -11 | File Check | The file requested was empty. |
| -10 | File Check | The file requested could not be found. |
| -3 | Any | Application and database version mismatch. |
| -2 | Any | A call to a deallocate function failed. |
| -1 | Any | A call to an allocate function failed. |
| 0 | Any | Successful completion. |
The following sections detail the specific interfaces between components for each program of the SMARTS system. The following programs have C++ and Fortran components.
Unless specified below, structures designated as input will have their member arrays allocated from C++ and so should not be altered in the Fortran code. Similarly, arrays designated as output, should be allocated in the Fortran code. In both cases, the C++ code will be responsible for deallocating the arrays once they are no longer needed.
All Latitude/Longitude coordinate arrays will be assumed to be in decimal degrees below and that the values indicate the center of the grid cell unless specified below.
In all cases, the components inside the options structure shall be allocated and deallocated from the C++ code.
The Re-sampled Radar Precipitation Mosaic (RRPM) program generates one of two different products. Firstly, it can create a product that combines the available DPA data into a mosaic, by either averaging or taking the maximum of data values for the same cell that occur in two or more radar fields; secondly it can generate a product based on the mosaic but include calibration of the individual radar files by using a fixed Z/R relationship to better describe the individual radar characteristics and utilizing the bias and exponent values used to generate the DPA files themselves to further improve precipitation estimates. In both cases the data is re-sampled to the DEOS grid.
Control over which product is generated by a specific run of the program is described below.
The program stores completed fields to disk in compressed (gzip) format. The gzstream interface (a C++ wrapper to the Zlib library) is used to achieve this.
This section describes the method whereby user or system settings for the product are transferred from C++ to the Fortran processing portion.
The call interface for this program on the C++ side will be:
IntegerArray x_coord_input;
IntegerArray y_coord_input;
FloatArray input_data;
FloatArray z_r_data;
FloatArray longitude_points;
FloatArray latitude_points;
FloatArray output_data;
IntegerOptions rrpm_int_options;
FloatOptions rrpm_float_options;
int error_code;
...
extern "C" {
void rrpm (IntegerArray *, IntegerArray *, FloatArray *, FloatArray *,
FloatArray*, FloatArray *, FloatArray *,
IntegerOptions *, FloatOptions *, int *);
}
...
rrpm (&x_coord_input, &y_coord_input, &input_data, &z_r_values,
&latitude_points, &longitude_points, &output_data,
&rrpm_int_options, &rrpm_float_options, &error_code);
The call interface for this program on the Fortran side will be:
subroutine rrpm(in_x_coord, in_y_coord, in_grid, in_z_r_data
+ out_lat_coord, out_long_coord, out_grid,
+ i_options, r_options, error_code)
!
implicit none
type(f_integer_array) :: in_x_coord ! HRAP X coordinate for data
type(f_integer_array) :: in_y_coord ! HRAP Y coordinate for data
type(f_real_array) :: in_grid ! Input DPA data in HRAP coordinates
type(f_real_array) :: in_z_r_data ! Z/R data for the individual radars
type(f_real_array) :: out_lat_coord ! Latitude value of data on DEOS real grid
type(f_real_array) :: out_long_coord ! Longitude value of data on DEOS real grid
type(f_real_array) :: out_grid ! Output re-sampled and mosaicked DEOS data on Real grid
type(f_integer_options) :: i_options ! rrpm integer options
type(f_real_options) :: r_options ! rrpm real options
integer error_code
For this interface, the out_lat_coord and out_long_coord derived types
will have values for order, and the option array, but the
other values will be set to missing (negative).
This section describes the data ordering conventions applied to the arrays passed to Fortran from C++.
If the integer option array has only one element, i.e. order is one, the a mosaic product
is to be generated, if order is greater than one, then a calibrated product is to be generated.
The input data array will consist of N blocks of DPA data, each one of size 131x131. The individual DPA data is sent row-wise from West to East and then North to South columnwise.
The input Z/R data array will consist of two pairs of data for each radar site (a total of 4 times the number of station files), in the same order as the data in the input data array. The first pair of data values will be Z bias and then Z exponent of the data file itself, the second pair will be the the Z bias and then Z exponent to be used in generating the revised precipitation estimate.
The order of the elements in the two input coordinate arrays will be the values as dictated by the data array.
No ordering convention has been established for the output data array.
The order of the elements in the two output coordinate arrays will be the values as dictated by the data array.
This section describes the options that are passed to Fortran from C++, their meanings and possible values.
The following table describes the integer processing options for the rrpm program.
The following table describes the floating-point processing options for the rrpm program.
Table 3. Interpretation of Floating-Point Options
| Number | Description | Example Values | Interpretation |
|---|---|---|---|
| 1 | Cell Center Latitude | -179.99 (DEOS value) | A value of any cell center latitude in degrees |
| 2 | Cell Center Longitude | -89.99 (DEOS value) | A value of any cell center longitude in degrees |
| 3 | Cell Spacing (width) | 0.02 (DEOS value) | The grid cell width in degrees |
| 4 | Cell Spacing (height) | 0.02 (DEOS value) | The grid cell height in degrees |
The Interploated Field Generator (IFGEN) program generates gridded products for all defined fields, other than the precipitation fileds which are produced by the RRPM program. Products are generated on the DEOS grid.
Control over which product is generated by a specific run of the program is described below.
The program stores completed fields to disk in compressed (gzip) format. The gzstream interface (a C++ wrapper to the Zlib library) is used to achieve this.
This section describes the method whereby user or system settings for the product are transferred from C++ to the Fortran processing portion.
The call interface for this program on the C++ side will be:
int product_type;
int n_stations;
FloatArray elevations;
FloatArray station_lat;
FloatArray station_long;
FloatArray station_data_values;
FloatArray station_data_values_supp;
FloatArray latitude_points;
FloatArray longitude_points;
FloatArray output_data;
FloatArray output_data_supp;
IntegerOptions ifgen_int_options;
FloatOptions ifgen_float_options;
int error_code;
...
extern "C" {
void ifgen (int *, int *, FloatArray *,
FloatArray *, FloatArray *, FloatArray *, FloatArray *,
FloatArray *, FloatArray *, FloatArray *, FloatArray *,
IntegerOptions *, FloatOptions *, int *);
}
...
ifgen (&product_type, &n_stations, &elevations,
&station_lat, &station_long, &station_data_values, &station_data_values_supp,
&latitude_points, &longitude_points, &output_data, &output_data_supp,
&ifgen_int_options, &ifgen_float_options, &error_code);
The call interface for this program on the Fortran side will be:
subroutine ifgen(product_type, n_stations, elevations,
+ station_lat, station_long, station_data_values, station_data_supp,
+ out_lat_coord, out_long_coord, out_grid, out_grid_supp,
+ i_options, r_options, error_code)
!
implicit none
integer product_type
integer n_stations
type(f_real_array) :: elevations ! ifgen real options
type(f_real_array) :: station_lat ! Latitude value of data on DEOS real grid
type(f_real_array) :: station_long ! Longitude value of data on DEOS real grid
type(f_real_array) :: station_data_values ! Input station data
type(f_real_array) :: station_data_supp ! Input station data (supplemental for vector data
type(f_real_array) :: out_lat_coord ! Latitude value of data on DEOS real grid
type(f_real_array) :: out_long_coord ! Longitude value of data on DEOS real grid
type(f_real_array) :: out_grid ! Output data on DEOS real grid
type(f_real_array) :: out_grid_supp ! Vector data supplement provided in this array if applicable
type(f_integer_options) :: i_options ! ifgen integer options
type(f_real_options) :: r_options ! ifgen real options
integer error_code
This section describes the data ordering conventions applied to the arrays passed to Fortran from C++.
The numerical product type is given in this table.
This section describes the options that are passed to Fortran from C++, their meanings and possible values.
The following table describes the integer processing options for the ifgen program.
Table 4. Interpretation of Integer Control Options
| Number | Description | Acceptable Values | Interpretation |
|---|---|---|---|
| 1 | Elevation effect inclusion | 0 | Do not include elevation effect |
| 1 | Include elevation effect | ||
| 2 | Interpolation parameters calibration | 0 | Do not calibrate interpolation parameters |
| 1 | Calibrate interpolation parameters effect |
The following table describes the floating-point processing options for the ifgen program.
Table 5. Interpretation of Floating-Point Options
| Number | Description | Example Values | Interpretation |
|---|---|---|---|
| 1 | Cell Center Latitude | -179.99 (DEOS value) | A value of any cell center latitude in degrees |
| 2 | Cell Center Longitude | -89.99 (DEOS value) | A value of any cell center longitude in degrees |
| 3 | Cell Spacing (width) | 0.02 (DEOS value) | The grid cell width in degrees |
| 4 | Cell Spacing (height) | 0.02 (DEOS value) | The grid cell height in degrees |
| 5 | Influence Radius | 100 | The value, in kilometers, for the interpolation influence radius |
[1] An entry in the program column indicates which specific program, if any, that the status message can occur or the general area of cause.