MAPL_CFIOMod Module

private subroutine MAPL_CFIOCreateFromBundle(MCFIO, NAME, CLOCK, BUNDLE, OFFSET, OUTPUT_GRID, CHUNKSIZE, FREQUENCY, LEVELS, DESCR, XYOFFSET, VCOORD, VUNIT, VSCALE, source, institution, comment, contact, format, EXPID, DEFLATE, GC, Order, NumCores, Nbits, TM, Conservative, vectorList, itemOrder, RC)

The subroutine MAPL_CFIOCreateFromBundle creates a MAPL_CFIO object from a Bundle. The MAPL_CFIO objects is opaque and its properties can only be set by this method at creation. Currently, its properties cannot be queried. The object is used only as a handle in write operations. It is not needed for reading.

Its non-optional arguments associate a NAME, an ESMF BUNDLE, and a CLOCK with the object. An ESMF TimeInterval OFFSET is an optional argument that sets an offset between the time on the clock when eriting and the time stamp used for the data (defaults to no offset).

The format optional argument determines whether the write will use the linked self-describing format (SDF) library (HDF or netcdf) or write GrADS readable flat files. Currently only the SDF library option is supported.

The remaining (optional) arguments are especialized and used primarily to support MAPL_History, or to provide documentation in the form of character strings that will be placed in corresponding attributes in the SDF file.

HIstory

• 19Apr2007 Todling
• Added ability to write out ak/bk
• Added experiment ID as optional argument

Arguments

private subroutine MAPL_CFIOCreateFromState(MCFIO, NAME, CLOCK, STATE, OFFSET, OUTPUT_GRID, CHUNKSIZE, FREQUENCY, LEVELS, DESCR, BUNDLE, XYOFFSET, VCOORD, VUNIT, VSCALE, source, institution, comment, contact, format, EXPID, DEFLATE, GC, Order, NumCores, Nbits, TM, CONSERVATIVE, RC)

The subroutine MAPL_CFIOCreateFromState creates a MAPL_CFIO object from a State. States are written by “serializing” all Fields in them, whether they are directly in the State or are contained within a hierarchy of embedded Bundles and States, into a single Bundle.

The Method optionally returns a pointer to the serialized ESMF Bundle, but this is not needed for MAPL_Write operations. Otherwise arguments are the same as for CreateFromBundle.

Its non-optional arguments associate a NAME, an ESMF BUNDLE, and a CLOCK with the object. An ESMF TimeInterval OFFSET is an optional argument that sets an offset between the time on the clock when eriting and the time stamp used for the data (defaults to no offset).

The format optional argument determines whether the write will use the linked self-describing format (SDF) library (HDF or netcdf) or write GrADS readable flat files. Currently only the SDF library option is supported. The remaining (optional) arguments are especialized and used primarily to support MAPL_History, or to provide documentation in the form of character strings that will be placed in corresponding attributes in the SDF file.

History

• 12Jun2007 Todling Added EXPID as opt argument

Arguments

public subroutine MAPL_CFIODestroy(MCFIO, RC)

The subroutine MAPL_CFIODestroy destroys a MAPL CFIO object. It closes any file associated with it and deallocates memory.

Arguments

private subroutine MAPL_CFIOReadState(FILETMPL, TIME, STATE, NOREAD, RC, VERBOSE, FORCE_REGRID, ONLY_VARS, TIME_IS_CYCLIC, TIME_INTERP, conservative, voting, ignoreCase, doParallel, getFrac)

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

private subroutine MAPL_CFIOReadBundle(FILETMPL, TIME, BUNDLE, NOREAD, RC, VERBOSE, FORCE_REGRID, ONLY_VARS, ONLY_LEVS, TIME_IS_CYCLIC, TIME_INTERP, conservative, voting, ignoreCase, doParallel, GSImode, getFrac, EXPID, collection_id)

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

private subroutine MAPL_CFIOReadField(VARN, FILETMPL, TIME, FIELD, RC, VERBOSE, FORCE_REGRID, TIME_IS_CYCLIC, TIME_INTERP, conservative, voting, ignoreCase, doParallel, getFrac)

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

private subroutine MAPL_CFIOReadArray3D(VARN, FILETMPL, TIME, GRID, farrayPtr, RC, VERBOSE, FORCE_REGRID, TIME_IS_CYCLIC, TIME_INTERP, conservative, voting, ignoreCase, doParallel, 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 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

private subroutine MAPL_CFIOReadArray2D(VARN, FILETMPL, TIME, GRID, farrayPtr, RC, VERBOSE, FORCE_REGRID, TIME_IS_CYCLIC, TIME_INTERP, conservative, voting, ignoreCase, doParallel, 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 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

private subroutine MAPL_CFIOWriteState(MCFIO, CLOCK, STATE, VERBOSE, NBITS, RC)

The subroutine MAPL_CFIOWriteState serializes an ESMF state into a Bundle and writes it to a file. Only the MAPL_CFIO object is a required argument as pointers to the actual data to be written is recorded in it during creation.

CLOCK, BUNDLE can be used to override the choice made at creation, but this is of dubious value, particularly for BUNDLE since it must be excatly conformant with the creation BUNDLE. NBITS if the number of bits of the mantissa to retain. This is used to write files with degraded precision, which can then be compressed with standard utilities. The default is no degradation of precision.

A note about compression. NetCDF-4, HDF-4 and HDF-5 all support transparent internal GZIP compression of the data being written. However, very little is gained by compressing float point fields from earth system models. Compression yields can be greatly increased by setting to zero bits in the mantissa of float numbers. On average 50% compression can be achieved, while preserving a meaningful accuracy in the fields. Unlike classical CF compression by means of scale_factor and add_offset attributes, internal GZIP compression requires no special handling by the users of the data. In fact, they do not even need to know that the data is compressed! At this point, MAPL_CFIO does not activate this GZIP compression feature in the files being written, but the resulting precision degredaded files can be compressed offline with the HDF-4 hrepack utility.

Arguments

private subroutine MAPL_CFIOWriteBundle(MCFIO, CLOCK, BUNDLE, VERBOSE, NBITS, created, RC)

The subroutine MAPL_CFIOWriteBundle writes an ESMF Bundle to a File. Only the MAPL_CFIO object is a required argument as pointers to the actual data to be written is recorded in it during creation.

CLOCK, BUNDLE can be used to override the choice made at creation, but this is of dubious value, particularly for BUNDLE since it must be excatly conformant with the creation BUNDLE. NBITS if the number of bits of the mantissa to retain. This is used to write files with degraded precision, which can then be compressed with standard utilities. The default is no degradation of precision.

A note about compression. NetCDF-4, HDF-4 and HDF-5 all support transparent internal GZIP compression of the data being written. However, very little is gained by compressing float point fields from earth system models. Compression yields can be greatly increased by setting to zero bits in the mantissa of float numbers. On average 50\% compression can be achieved, while preserving a meaningful accuracy in the fields. Unlike classical CF compression by means of scale_factor and add_offset attributes, internal GZIP compression requires no special handling by the users of the data. In fact, they do not even need to know that the data is compressed! At this point, MAPL_CFIO does not activate this GZIP compression feature in the files being written, but the resulting precision degredaded files can be compressed offline with the HDF-4 hrepack* utility.

Arguments

private subroutine MAPL_CFIOCreateFromBundle(MCFIO, NAME, CLOCK, BUNDLE, OFFSET, OUTPUT_GRID, CHUNKSIZE, FREQUENCY, LEVELS, DESCR, XYOFFSET, VCOORD, VUNIT, VSCALE, source, institution, comment, contact, format, EXPID, DEFLATE, GC, Order, NumCores, Nbits, TM, Conservative, vectorList, itemOrder, RC)

The subroutine MAPL_CFIOCreateFromBundle creates a MAPL_CFIO object from a Bundle. The MAPL_CFIO objects is opaque and its properties can only be set by this method at creation. Currently, its properties cannot be queried. The object is used only as a handle in write operations. It is not needed for reading.

Its non-optional arguments associate a NAME, an ESMF BUNDLE, and a CLOCK with the object. An ESMF TimeInterval OFFSET is an optional argument that sets an offset between the time on the clock when eriting and the time stamp used for the data (defaults to no offset).

The format optional argument determines whether the write will use the linked self-describing format (SDF) library (HDF or netcdf) or write GrADS readable flat files. Currently only the SDF library option is supported.

The remaining (optional) arguments are especialized and used primarily to support MAPL_History, or to provide documentation in the form of character strings that will be placed in corresponding attributes in the SDF file.

HIstory

• 19Apr2007 Todling
• Added ability to write out ak/bk
• Added experiment ID as optional argument

Arguments

private subroutine MAPL_CFIOCreateFromState(MCFIO, NAME, CLOCK, STATE, OFFSET, OUTPUT_GRID, CHUNKSIZE, FREQUENCY, LEVELS, DESCR, BUNDLE, XYOFFSET, VCOORD, VUNIT, VSCALE, source, institution, comment, contact, format, EXPID, DEFLATE, GC, Order, NumCores, Nbits, TM, CONSERVATIVE, RC)

The subroutine MAPL_CFIOCreateFromState creates a MAPL_CFIO object from a State. States are written by “serializing” all Fields in them, whether they are directly in the State or are contained within a hierarchy of embedded Bundles and States, into a single Bundle.

The Method optionally returns a pointer to the serialized ESMF Bundle, but this is not needed for MAPL_Write operations. Otherwise arguments are the same as for CreateFromBundle.

Its non-optional arguments associate a NAME, an ESMF BUNDLE, and a CLOCK with the object. An ESMF TimeInterval OFFSET is an optional argument that sets an offset between the time on the clock when eriting and the time stamp used for the data (defaults to no offset).

The format optional argument determines whether the write will use the linked self-describing format (SDF) library (HDF or netcdf) or write GrADS readable flat files. Currently only the SDF library option is supported. The remaining (optional) arguments are especialized and used primarily to support MAPL_History, or to provide documentation in the form of character strings that will be placed in corresponding attributes in the SDF file.

History

• 12Jun2007 Todling Added EXPID as opt argument

Arguments

private subroutine MAPL_CFIOReadState(FILETMPL, TIME, STATE, NOREAD, RC, VERBOSE, FORCE_REGRID, ONLY_VARS, TIME_IS_CYCLIC, TIME_INTERP, conservative, voting, ignoreCase, doParallel, getFrac)

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

private subroutine MAPL_CFIOReadBundle(FILETMPL, TIME, BUNDLE, NOREAD, RC, VERBOSE, FORCE_REGRID, ONLY_VARS, ONLY_LEVS, TIME_IS_CYCLIC, TIME_INTERP, conservative, voting, ignoreCase, doParallel, GSImode, getFrac, EXPID, collection_id)

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

private subroutine MAPL_CFIOReadField(VARN, FILETMPL, TIME, FIELD, RC, VERBOSE, FORCE_REGRID, TIME_IS_CYCLIC, TIME_INTERP, conservative, voting, ignoreCase, doParallel, getFrac)

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

private subroutine MAPL_CFIOReadArray3D(VARN, FILETMPL, TIME, GRID, farrayPtr, RC, VERBOSE, FORCE_REGRID, TIME_IS_CYCLIC, TIME_INTERP, conservative, voting, ignoreCase, doParallel, 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 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

private subroutine MAPL_CFIOReadArray2D(VARN, FILETMPL, TIME, GRID, farrayPtr, RC, VERBOSE, FORCE_REGRID, TIME_IS_CYCLIC, TIME_INTERP, conservative, voting, ignoreCase, doParallel, 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 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

private subroutine MAPL_CFIOReadParallel_(bundlelist, filelist, time, blocksize, regridMethod, gsiMode, timelist, rc)

Arguments

private subroutine MAPL_CFIOWriteState(MCFIO, CLOCK, STATE, VERBOSE, NBITS, RC)

The subroutine MAPL_CFIOWriteState serializes an ESMF state into a Bundle and writes it to a file. Only the MAPL_CFIO object is a required argument as pointers to the actual data to be written is recorded in it during creation.

CLOCK, BUNDLE can be used to override the choice made at creation, but this is of dubious value, particularly for BUNDLE since it must be excatly conformant with the creation BUNDLE. NBITS if the number of bits of the mantissa to retain. This is used to write files with degraded precision, which can then be compressed with standard utilities. The default is no degradation of precision.

A note about compression. NetCDF-4, HDF-4 and HDF-5 all support transparent internal GZIP compression of the data being written. However, very little is gained by compressing float point fields from earth system models. Compression yields can be greatly increased by setting to zero bits in the mantissa of float numbers. On average 50% compression can be achieved, while preserving a meaningful accuracy in the fields. Unlike classical CF compression by means of scale_factor and add_offset attributes, internal GZIP compression requires no special handling by the users of the data. In fact, they do not even need to know that the data is compressed! At this point, MAPL_CFIO does not activate this GZIP compression feature in the files being written, but the resulting precision degredaded files can be compressed offline with the HDF-4 hrepack utility.

Arguments

private subroutine MAPL_CFIOWriteBundle(MCFIO, CLOCK, BUNDLE, VERBOSE, NBITS, created, RC)

The subroutine MAPL_CFIOWriteBundle writes an ESMF Bundle to a File. Only the MAPL_CFIO object is a required argument as pointers to the actual data to be written is recorded in it during creation.

CLOCK, BUNDLE can be used to override the choice made at creation, but this is of dubious value, particularly for BUNDLE since it must be excatly conformant with the creation BUNDLE. NBITS if the number of bits of the mantissa to retain. This is used to write files with degraded precision, which can then be compressed with standard utilities. The default is no degradation of precision.

A note about compression. NetCDF-4, HDF-4 and HDF-5 all support transparent internal GZIP compression of the data being written. However, very little is gained by compressing float point fields from earth system models. Compression yields can be greatly increased by setting to zero bits in the mantissa of float numbers. On average 50\% compression can be achieved, while preserving a meaningful accuracy in the fields. Unlike classical CF compression by means of scale_factor and add_offset attributes, internal GZIP compression requires no special handling by the users of the data. In fact, they do not even need to know that the data is compressed! At this point, MAPL_CFIO does not activate this GZIP compression feature in the files being written, but the resulting precision degredaded files can be compressed offline with the HDF-4 hrepack* utility.

Arguments