MAPL_CFIORead Interface

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'.

Design Issue

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.

Arguments

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:

• 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 {\em 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
• BUNDLE An ESMF Bundle to read the data in. When the Bundle is empty one field is added for each variable present in the input file, and the necessary memory allocated according to the ESMF grid present in the Bundle.
• [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'.

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.

Design Issues

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.

Arguments

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'.

Design Issues

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.

Arguments

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 toESMF_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’`.

Design Issues

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.

Arguments

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 toESMF_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’`.

Design Issues

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.

Arguments