INTERP3() and interp3c()

Fortran version:

    LOGICAL FUNCTION INTERP3( FNAME, VNAME, CALLER, 
 &                            JDATE, JTIME, BSIZE, BUFFER )
    LOGICAL FUNCTION INTERPX( FNAME, VNAME, CALLER, 
 &                            COL0, COL1, ROW0, ROW1, LAY0, LAY1,
 &                            JDATE, JTIME, BUFFER )
        CHARACTER*(*)   FNAME     !  file name for query
        CHARACTER*(*)   VNAME     !  vble  name   (or ALLVAR3 (='ALL'))
        CHARACTER*(*)   CALLER    !  name of caller for logging
        INTEGER         COL0      !  lower col   bound for INTERPX
        INTEGER         COL1      !  upper col   bound for INTERPX
        INTEGER         ROW0      !  lower row   bound for INTERPX
        INTEGER         ROW1      !  upper row   bound for INTERPX
        INTEGER         LAY0      !  lower layer bound for INTERPX
        INTEGER         LAY1      !  upper layer bound for INTERPX
        INTEGER         JDATE     !  date, formatted YYYYDDD
        INTEGER         JTIME     !  time, formatted HHMMSS
        INTEGER         BSIZE     !  data volume (words) being read
        <type>       BUFFER( BSIZE ) !  array to hold input

C version:

interp3c() and interpxc() are C wrappers calling the Fortran INTERP3() and INTERPX().

    int interp3c( const char * fname ,
                  const char * vname ,
                  const char * caller,
                  int          jdate ,
                  int          jtime ,
                  int          bsize ,
                  void       * buffer )
    int interpxc( const char * fname ,
                  const char * vname ,
                  const char * caller,
                  int          col0 ,
                  int          col1 ,
                  int          row0 ,
                  int          row1 ,
                  int          lay0 ,
                  int          lay1 ,
                  int          jdate ,
                  int          jtime ,
                  void       * buffer )

NOTE on INTERPX:

INTERPX() is new with I/O&bnsp;API Version 2.2

Summary:

Probably the most-useful input routines for modelers (as opposed to those constructing analysis tools) since they encapsulate so many "routine" tasks for the model-writing user -- not strictly required, but terribly convenient to have.

Do linear-time interpolation of data from Models-3 data file with logical name FNAME for variable with name VNAME, for the date and time JDATE (coded YYYYDDD), JTIME (HHMMSS), with optimized memory allocation, reading, etc., handled behind the scenes.

INTERP3() checks size BSIZE of the buffer to hold the data against the size calculated from values in the file header (and insists that they match); returns a full-grid result.

INTERPX() checks window bounds COL0, COL1, ROW0, ROW1, LAY0, LAY1 against the dimension values in the file header (and insists that they match); returns a partial-grid result:

For time independent files, JDATE:JTIME are ignored.

Returns .TRUE. (or 1) if the operation succeeds, .FALSE. (or 0) if it fails. For failure, writes a log message indicating the nature of the failure.

Calls INIT3() and also OPEN3() if necessary (opening the file for read-only if it does so).

See also

DDTVAR3,
READ3,
WRITE3,
XTRACT3,

Preconditions:

INCLUDE 'IODECL3.EXT' for Fortran, or #include "iodecl3.h" for C.

FNAME and VNAME must have length at most 16, exclusive of trailng blanks.

Valid BSIZE for INTERP3() or COL0, COL1, ROW0, ROW1, LAY0, LAY1 for INTERPX().

INTERPX() not supported yet for virtual files (netCDF only).

JDATE and JTIME must be expressed in terms of Models-3 date and time conventions.

basic data type VTYPE3D for the variable must be M3REAL for releases prior to the May 3, 2002 Version 2.2-beta, or M3REAL or M3DBLE for subsequent releases.

Fortran Usage:

For Fortran-90 declarations and interface checking:
    USE M3UTILIO
    

    ...
    USE M3UTILIO
    ...
    INTEGER     NCOLS,      NROWS,      NLAYS
    PARAMETER ( NCOLS = ??, NROWS = ??, NLAYS = ?? )
    ...
    REAL  SO4( NCOLS, NROWS, NLAYS )
    REAL  SFCNOX( NCOLS, NROWS )
C            NOTE:  It isn't required that the name of the Fortran
C            variable match the name of the file-variable, but it
C            can often help the maintainability of the code if it does.
    ...
    IF ( INTERP3( 'MYFILE', 'SO4', 1988021, 123730, 
 &              NCOLS*NROWS*NLAYS, SO4 ) ) THEN
C            Variable 'SO4' interpolated to 12:37:30 Jan 21, 1988
C            from MYFILE and put into array SO4.
        ...
    ELSE
C           Error:  see program log for further info.
        ...
    END IF
    ...
    IF ( INTERPX( 'MYFILE', 'NOX', 1988021, 123730, 
 &              1, NCOLS, 1, NROWS, 1, 1, SFCNOX ) ) THEN
C            Layer 1 of variable 'NOX' interpolated to
C            12:37:30 Jan 21, 1988
C            from MYFILE and put into array SFCNOX.
        ...
    ELSE
C           Error:  see program log for further info.
        ...
    END IF
    ...

C Usage:

    ...
    #include "iodecl3.h"
    ...
    float  hno3[ NLAYS ][ NROWS ][ NCOLS ] ;
    ...
    if ( interp3c( "MYFILE", "HNO3", 1988021, 123000, 
                   NCOLS*NROWS*NLAYS, hno3 ) )
        {
            /*  Variable 'HNO3' interpolated to date and time 
                12:37:30  Jan 21, 1988 from MYFILE and put into 
                array hno3
            */
        ...
        }
    else
        {
            /*  Error:  see program log for further info.  */
        ...
        }
    ...


Previous: INIT3

Next: IOPARMS3

Up: I/O API: Public Routines

To: Models-3/EDSS I/O API: The Help Pages