PUBLIC INTERFACE ~ PUBLIC DATA ~ PUBLIC ROUTINES ~ NAMELIST ~ DIAGNOSTIC FIELDS ~ ERROR MESSAGES ~ REFERENCES ~ NOTES

## Module time_interp_external_mod

Contact: M.J. Harrison
Reviewers: Harper Simmons
Change History: WebCVS Log

#### OVERVIEW

Perform I/O and time interpolation of external fields (contained in a file).

Perform I/O and time interpolation for external fields. Uses udunits library to calculate calendar dates and convert units. Allows for reading data decomposed across model horizontal grid using optional domain2d argument
data are defined over data domain for domain2d data (halo values are NOT updated by this module)

#### OTHER MODULES USED

             mpp_mod
          mpp_io_mod
    time_manager_mod
    get_cal_time_mod
     mpp_domains_mod
     time_interp_mod
      axis_utils_mod
             fms_mod
        platform_mod
    horiz_interp_mod

#### PUBLIC INTERFACE

time_interp_external_init:
init_external_field:
time_interp_external:
get_external_field_size:
time_interp_external_exit:

OUTPUT

  `err_field_not_found` | [integer]
  `success` | [integer]

(To be used in combination with optional argument ierr of function init_external_field)

#### PUBLIC ROUTINES

1. #### time_interp_external_init

   DESCRIPTION
     Initialize the time_interp_external module

2. #### init_external_field

   DESCRIPTION
     initialize an external field. Buffer entire field to memory (default) or store "num_io_buffers" in memory to reduce memory allocations. distributed reads are supported using the optional "domain" flag. Units conversion via the optional "desired_units" flag using udunits_mod.
     Return integer id of field for future calls to time_interp_external.
   INPUT

     `file` | filename [character(len=*)]
     `fieldname` | fieldname (in file) [character(len=*)]
     `format` | mpp_io flag for format of file (optional). Currently only "MPP_NETCDF" supported [integer]
     `threading` | mpp_io flag for threading (optional). "MPP_SINGLE" means root pe reads global field and distributes to other PEs "MPP_MULTI" means all PEs read data [integer]
     `domain` | domain flag (optional) [mpp_domains_mod:domain2d]
     `desired_units` | Target units for data (optional), e.g. convert from deg_K to deg_C. Failure to convert using udunits will result in failure of this module. [character(len=*)]
     `verbose` | verbose flag for debugging (optional). [logical]

   INPUT/OUTPUT

     `axis_centers` | MPP_IO axistype array for grid centers ordered X-Y-Z-T (optional). [axistype, dimension(4)]
     `axis_sizes` | array of axis lengths ordered X-Y-Z-T (optional). [integer, dimension(4)]

   OUTPUT

     `ierr` | returned value=err_field_not_found if field does not exist, returned value=success otherwise (optional). Program will terminate fatally if field does not exist and ierr is not present. [integer]

3. #### time_interp_external

   DESCRIPTION
     Provide data from external file interpolated to current model time. Data may be local to current processor or global, depending on "init_external_field" flags.
   INPUT

     `index` | index of external field from previous call to init_external_field [integer]
     `time` | target time for data [time_manager_mod:time_type]
     `interp` | time_interp_external defined interpolation method (optional). Currently this module only supports LINEAR_TIME_INTERP. [integer]
     `verbose` | verbose flag for debugging (optional). [logical]

   INPUT/OUTPUT

     `data` | global or local data array [real, dimension(:,:),(:,:,:)]

4. #### get_external_field_size

   DESCRIPTION
     return size of field after call to init_external_field. Ordering is X/Y/Z/T. This call only makes sense for non-distributed reads.
   INPUT

     `index` | returned from previous call to init_external_field. [integer]

5. #### time_interp_external_exit

   DESCRIPTION
     exit time_interp_external_mod. Close all open files and release storage

#### NAMELIST

&time_interp_external_nml

`num_io_buffers`

size of record dimension for internal buffer. This is useful for tuning i/o performance particularly for large datasets (e.g. daily flux fields)
[integer]

#### DATA SETS

None.

#### ERROR MESSAGES

None.

top