The subroutine MAPL_CFIOReadState
serializes an ESMF state into a Bundle and reads its content from
a file. The file is open, read from, and closed on exit. The
arguments are:
- FILETMPL A GrADS-style file name template. In its simplest
form is the full path name for the file to be read. However, it
can contain the following tokens which will be expanded from
the current time in TIME:
- %y4 4 digits for year
- %m2 2 digits for month, to expand to 01, 02, .., 12
- %m3 3 digits for month, to expand to jan, feb, mar, …, dec
- %d2 2 digits for day
- %h2 2 digits for hour
- %n2 2 digits for minutes
Example: if FILETMPL = 'forecast.%y4-%m2-%d2_%h2z.nc4'
, and the clock
says it is 18Z on 05 February 2007, the template will expand in the
following file name: 'forecast.2007-02-05_18Z.nc4'
- TIME The ESMF time to read from the file
- STATE An ESMF State to read the data in. Usually used in conjubction
with ONLY_VARS.
- [NOREAD] If .TRUE., no data is actually read into the Bundle. This is
useful to define a Bundle with the same variables as presented in the
file, which in turn can be used to created a MAPL_CFIO
object for
writing.
- [RC] Error return code; set to ESMF_SUCCESS
if all is well.
- [VERBOSE] If .TRUE., prints progress messages to STDOUT; useful
for debugging.
- [FORCE_REGRID] Obsolete; kept for backward compatibility but
has no effect.
- [TIME_IS_CYCLIC] If .TRUE. it says that the input file is periodic
in time. Useful for reading climatological files. For example, if the
input file has 12 monthly means from January to December of 2001, setting
this option to .TRUE. allows one to read this data for any other year. See
note below regarding issues with reading monthly mean data.
- [TIME_INTERP] If .TRUE., the input file does not have to coincide with the
actual times on file. In such cases, the data for the bracketing times are
read and the data is properly interpolated in time. The input time, though,
need to be within the range of times present on file
(unless TIME_IS_CYCLIC is specified).
- [ONLY_VARS] A list of comma separated vafriables to be read from the
file. By default, all variables are read from the file. This option allows
one to read a subset of vafriables. Example: ONLY\_VARS='u,v,ps'
.
The input argument TIME should be replaced with CLOCK for consistency with the rest of the API. One should also provide an interface involving the MAPL CFIO object.
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
character(len=*), | intent(in) | :: | FILETMPL | |||
type(ESMF_Time), | intent(inout) | :: | TIME | |||
type(ESMF_State), | intent(inout) | :: | STATE | |||
logical, | intent(in), | optional | :: | NOREAD | ||
integer, | intent(out), | optional | :: | RC | ||
logical, | intent(in), | optional | :: | VERBOSE | ||
logical, | intent(in), | optional | :: | FORCE_REGRID | ||
character(len=*), | intent(in), | optional | :: | ONLY_VARS |
comma separated, no spaces |
|
logical, | intent(in), | optional | :: | TIME_IS_CYCLIC | ||
logical, | intent(in), | optional | :: | TIME_INTERP | ||
logical, | intent(in), | optional | :: | conservative | ||
logical, | intent(in), | optional | :: | voting | ||
logical, | intent(in), | optional | :: | ignoreCase | ||
logical, | intent(in), | optional | :: | doParallel | ||
integer, | intent(in), | optional | :: | getFrac |
The subroutine MAPL_CFIOReadBundle` reads an ESMF Bundle from a file on a given time. The file is open, read from, and closed on exit. The arguments are:
'forecast.%y4-%m2-%d2_%h2z.nc4'
, and the clock
says it is 18Z on 05 February 2007, the template will expand in the
following file name: 'forecast.2007-02-05_18Z.nc4'
MAPL_CFIO
object for
writing.ESMF_SUCCESS
if all is well.ONLY_VARS='u,v,ps'
.A note about storing monthly climatological data. As per the CF conventions, month is not a well defined unit of time, as the time step is not constant throughout the year. When storing 12 months of climatological data one way around it is to use an average number of hours: use 732 or 730 hours depending on whether the year recorded in the file is a leap-year or not.
The input argument TIME should be replaced with CLOCK for consistency with the rest of the API. One should also provide an interface involving the MAPL CFIO object.
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
character(len=*), | intent(in) | :: | FILETMPL | |||
type(ESMF_Time), | intent(inout) | :: | TIME | |||
type(ESMF_FIELDBUNDLE), | intent(inout) | :: | BUNDLE | |||
logical, | intent(in), | optional | :: | NOREAD | ||
integer, | intent(out), | optional | :: | RC | ||
logical, | intent(in), | optional | :: | VERBOSE | ||
logical, | intent(in), | optional | :: | FORCE_REGRID | ||
character(len=*), | intent(in), | optional | :: | ONLY_VARS | ||
real, | intent(in), | optional | :: | ONLY_LEVS(:) | ||
logical, | intent(in), | optional | :: | TIME_IS_CYCLIC | ||
logical, | intent(in), | optional | :: | TIME_INTERP | ||
logical, | intent(in), | optional | :: | conservative | ||
logical, | intent(in), | optional | :: | voting | ||
logical, | intent(in), | optional | :: | ignoreCase | ||
logical, | intent(in), | optional | :: | doParallel | ||
logical, | intent(in), | optional | :: | GSImode | ||
integer, | intent(in), | optional | :: | getFrac | ||
character(len=*), | intent(in), | optional | :: | EXPID | ||
integer, | intent(in), | optional | :: | collection_id |
The subroutine MAPL_CFIOReadField
reads a variable from a file and stores it on an ESMF Field.
The file is open, read from, and closed on exit. The
arguments are:
- VARN The variable name.
- FILETMPL A GrADS-style file name template. In its simplest
form is the full path name for the file to be read. However, it
can contain the following tokens which will be expanded from
the current time in TIME:
- %y4 4 digits for year
- %m2 2 digits for month, to expand to 01, 02, .., 12
- %m3 3 digits for month, to expand to jan, feb, mar, …, dec
- %d2 2 digits for day
- %h2 2 digits for hour
- %n2 2 digits for minutes
Example: if FILETMPL = 'forecast.%y4-%m2-%d2_%h2z.nc4'
, and the clock
says it is 18Z on 05 February 2007, the template will expand in the
following file name: forecast.2007-02-05_18Z.nc4'
- TIME The ESMF time to read from the file
- [RC] Error return code; set to ESMF_SUCCESS
if all is well.
- [VERBOSE] If .TRUE., prints progress messages to STDOUT; useful
for debugging.
- [FORCE_REGRID] Obsolete; kept for backward compatibility but
has no effect.
- [TIME_IS_CYCLIC] If .TRUE. it says that the input file is periodic
in time. Useful for reading climatological files. For example, if the
input file has 12 monthly means from January to December of 2001, setting
this option to .TRUE. allows one to read this data for any other year. See
note below regarding issues with reading monthly mean data.
- [TIME_INTERP] If .TRUE., the input file does not have to coincide with the
actual times on file. In such cases, the data for the bracketing times are
read and the data is properly interpolated in time. The input time, though,
need to be within the range of times present on file
(unless TIME_IS_CYCLIC is specified).
- [ONLY_VARS] A list of comma separated vafriables to be read from the
file. By default, all variables are read from the file. This option allows
one to read a subset of vafriables. Example: ONLY\_VARS='u,v,ps'
.
The input argument {\tt TIME} should be replaced with CLOCK for consistency with the rest of the API. The input GRID is not necessary as it can be found inside the field. One should also provide an interface involving the MAPL CFIO object.
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
character(len=*), | intent(in) | :: | VARN |
Variable name |
||
character(len=*), | intent(in) | :: | FILETMPL |
File name |
||
type(ESMF_Time), | intent(inout) | :: | TIME | |||
type(ESMF_Field), | intent(inout) | :: | FIELD | |||
integer, | intent(out), | optional | :: | RC | ||
logical, | intent(in), | optional | :: | VERBOSE | ||
logical, | intent(in), | optional | :: | FORCE_REGRID | ||
logical, | intent(in), | optional | :: | TIME_IS_CYCLIC | ||
logical, | intent(in), | optional | :: | TIME_INTERP | ||
logical, | intent(in), | optional | :: | conservative | ||
logical, | intent(in), | optional | :: | voting | ||
logical, | intent(in), | optional | :: | ignoreCase | ||
logical, | intent(in), | optional | :: | doParallel | ||
integer, | intent(in), | optional | :: | getFrac |
The subroutine MAPL_CFIOReadArray3D
reads a variable from a file and stores it on an 3D Fortrran array.
The file is open, read from, and closed on exit. The
arguments are:
- VARN The variable name.
- FILETMPL A GrADS-style file name template. In its simplest
form is the full path name for the file to be read. However, it
can contain the following tokens which will be expanded from
the current time in TIME:
- %y4 4 digits for year
- %m2 2 digits for month, to expand to 01, 02, .., 12
- %m3 3 digits for month, to expand to jan, feb, mar, …, dec
- %d2 2 digits for day
- %h2 2 digits for hour
- %n2 2 digits for minutes
Example: if FILETMPL = 'forecast.%y4-%m2-%d2_%h2z.nc4'
, and the clock
says it is 18Z on 05 February 2007, the template will expand in the
following file name: `forecast.2007-02-05\_18Z.nc4''
- **TIME** The ESMF time to read from the file
- **GRID** The ESMF grid associated with the Field. The data will be
(horizontally) interpolated to this grid if necessary.
- **[RC]** Error return code; set to
ESMF_SUCCESSif all is well.
- **[VERBOSE]}] If .TRUE., prints progress messages to STDOUT; useful
for debugging.
- **[FORCE_REGRID]** Obsolete; kept for backward compatibility but
has no effect.
- **[TIME_IS_CYCLIC]** If .TRUE. it says that the input file is periodic
in time. Useful for reading climatological files. For example, if the
input file has 12 monthly means from January to December of 2001, setting
this option to .TRUE. allows one to read this data for any other year. See
note below regarding issues with reading monthly mean data.
- **[TIME_INTERP]** If .TRUE., the input file does not have to coincide with the
actual times on file. In such cases, the data for the bracketing times are
read and the data is properly interpolated in time. The input time, though,
need to be within the range of times present on file
(unless *TIME_IS_CYCLIC* is specified).
- **[ONLY_VARS]** A list of comma separated vafriables to be read from the
file. By default, all variables are read from the file. This option allows
one to read a subset of vafriables. Example:
ONLY_VARS=’u,v,ps’`.
The input argument TIME should be replaced with CLOCK for consistency with the rest of the API. One should also provide an interface involving the MAPL CFIO object.
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
character(len=*), | intent(in) | :: | VARN |
Variable name |
||
character(len=*), | intent(in) | :: | FILETMPL |
File name |
||
type(ESMF_Time), | intent(inout) | :: | TIME | |||
type(ESMF_Grid), | intent(in) | :: | GRID | |||
real, | pointer | :: | farrayPtr(:,:,:) | |||
integer, | intent(out), | optional | :: | RC | ||
logical, | intent(in), | optional | :: | VERBOSE | ||
logical, | intent(in), | optional | :: | FORCE_REGRID | ||
logical, | intent(in), | optional | :: | TIME_IS_CYCLIC | ||
logical, | intent(in), | optional | :: | TIME_INTERP | ||
logical, | intent(in), | optional | :: | conservative | ||
logical, | intent(in), | optional | :: | voting | ||
logical, | intent(in), | optional | :: | ignoreCase | ||
logical, | intent(in), | optional | :: | doParallel | ||
integer, | intent(in), | optional | :: | getFrac |
The subroutine MAPL_CFIOReadArray2D
reads a variable from a file and stores it on an 2D Fortrran array.
The file is open, read from, and closed on exit. The
arguments are:
- VARN The variable name.
- FILETMPL A GrADS-style file name template. In its simplest
form is the full path name for the file to be read. However, it
can contain the following tokens which will be expanded from
the current time in TIME:
- %y4 4 digits for year
- %m2 2 digits for month, to expand to 01, 02, .., 12
- %m3 3 digits for month, to expand to jan, feb, mar, …, dec
- %d2 2 digits for day
- %h2 2 digits for hour
- %n2 2 digits for minutes
Example: if FILETMPL = 'forecast.%y4-%m2-%d2_%h2z.nc4'
, and the clock
says it is 18Z on 05 February 2007, the template will expand in the
following file name: `forecast.2007-02-05\_18Z.nc4''
- **TIME** The ESMF time to read from the file
- **GRID** The ESMF grid associated with the Field. The data will be
(horizontally) interpolated to this grid if necessary.
- **[RC]** Error return code; set to
ESMF_SUCCESSif all is well.
- **[VERBOSE]}] If .TRUE., prints progress messages to STDOUT; useful
for debugging.
- **[FORCE_REGRID]** Obsolete; kept for backward compatibility but
has no effect.
- **[TIME_IS_CYCLIC]** If .TRUE. it says that the input file is periodic
in time. Useful for reading climatological files. For example, if the
input file has 12 monthly means from January to December of 2001, setting
this option to .TRUE. allows one to read this data for any other year. See
note below regarding issues with reading monthly mean data.
- **[TIME_INTERP]** If .TRUE., the input file does not have to coincide with the
actual times on file. In such cases, the data for the bracketing times are
read and the data is properly interpolated in time. The input time, though,
need to be within the range of times present on file
(unless *TIME_IS_CYCLIC* is specified).
- **[ONLY_VARS]** A list of comma separated vafriables to be read from the
file. By default, all variables are read from the file. This option allows
one to read a subset of vafriables. Example:
ONLY_VARS=’u,v,ps’`.
The input argument TIME should be replaced with CLOCK for consistency with the rest of the API. One should also provide an interface involving the MAPL CFIO object.
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
character(len=*), | intent(in) | :: | VARN |
Variable name |
||
character(len=*), | intent(in) | :: | FILETMPL |
File name |
||
type(ESMF_Time), | intent(inout) | :: | TIME | |||
type(ESMF_Grid), | intent(in) | :: | GRID | |||
real, | pointer | :: | farrayPtr(:,:) | |||
integer, | intent(out), | optional | :: | RC | ||
logical, | intent(in), | optional | :: | VERBOSE | ||
logical, | intent(in), | optional | :: | FORCE_REGRID | ||
logical, | intent(in), | optional | :: | TIME_IS_CYCLIC | ||
logical, | intent(in), | optional | :: | TIME_INTERP | ||
logical, | intent(in), | optional | :: | conservative | ||
logical, | intent(in), | optional | :: | voting | ||
logical, | intent(in), | optional | :: | ignoreCase | ||
logical, | intent(in), | optional | :: | doParallel | ||
integer, | intent(in), | optional | :: | getFrac |