Module time_interp_external

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

OUTPUT

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

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

PUBLIC ROUTINES

time_interp_external_init

DESCRIPTION

Initialize the time_interp_external module

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]

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(:,:),(:,:,:)]

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]
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

DATA SETS

None.

ERROR MESSAGES

None.

top