MAPL_CFIOMod Module

MODULE: MAPL_CFIOMod

Author: GMAO SI-Team

The module MAPL_CFIO provides Climate and Forecast (CF) compliant I/O methods for high level ESMF data types by using the CFIO Library. It currently includes read-write support for ESMF Bundles and States, and read-only support for ESMF Fields and Fortran arrays. The API consists of 4 basic methods:

  • MAPL_CFIORead
  • MAPL_CFIOCreate
  • MAPL_CFIOWrite
  • MAPL_CFIODestroy

Uses

Used by

  • module~~mapl_cfiomod~~UsedByGraph module~mapl_cfiomod MAPL_CFIOMod module~mapl_extdatagridcomp2g MAPL_ExtDataGridComp2G module~mapl_extdatagridcomp2g->module~mapl_cfiomod module~mapl_extdatagridcompmod MAPL_ExtDataGridCompMod module~mapl_extdatagridcompmod->module~mapl_cfiomod module~mapl_historycollectionmod MAPL_HistoryCollectionMod module~mapl_historycollectionmod->module~mapl_cfiomod module~mapl_historygridcompmod MAPL_HistoryGridCompMod module~mapl_historygridcompmod->module~mapl_cfiomod module~mapl_historygridcompmod->module~mapl_historycollectionmod module~mapl_simplebundlemod MAPL_SimpleBundleMod module~mapl_simplebundlemod->module~mapl_cfiomod module~maplbase_mod MAPLBase_Mod module~maplbase_mod->module~mapl_cfiomod module~maplbase_mod->module~mapl_simplebundlemod proc~initialize_io_clients_servers ExtDataDriver%initialize_io_clients_servers proc~initialize_io_clients_servers->module~mapl_cfiomod program~regrid_util Regrid_Util program~regrid_util->module~mapl_cfiomod program~utcfio utCFIO program~utcfio->module~mapl_cfiomod program~utcfio~3 utCFIO program~utcfio~3->module~mapl_cfiomod module~extdata_drivergridcompmod ExtData_DriverGridCompMod module~extdata_drivergridcompmod->module~mapl_extdatagridcomp2g module~extdata_drivergridcompmod->module~mapl_extdatagridcompmod module~extdata_drivergridcompmod->module~mapl_historygridcompmod module~mapl MAPL module~mapl->module~maplbase_mod module~mapl_capgridcompmod MAPL_CapGridCompMod module~mapl_capgridcompmod->module~mapl_extdatagridcomp2g module~mapl_capgridcompmod->module~mapl_extdatagridcompmod module~mapl_capgridcompmod->module~mapl_historygridcompmod module~mapl_historycollectionvectormod MAPL_HistoryCollectionVectorMod module~mapl_historycollectionvectormod->module~mapl_historycollectionmod module~mapl_nuopcwrappermod MAPL_NUOPCWrapperMod module~mapl_nuopcwrappermod->module~maplbase_mod module~mapl_stringfieldsetmapmod MAPL_StringFieldSetMapMod module~mapl_stringfieldsetmapmod->module~mapl_historycollectionmod module~rutmod RUTMod module~rutmod->module~mapl_extdatagridcompmod module~rutmod->module~maplbase_mod module~test_cfio_bundle Test_CFIO_Bundle module~test_cfio_bundle->module~maplbase_mod program~tstqsat tstqsat program~tstqsat->module~maplbase_mod program~ut_extdata ut_ExtData program~ut_extdata->module~mapl_extdatagridcompmod program~ut_extdata->module~maplbase_mod program~utcfio~2 utCFIO program~utcfio~2->module~maplbase_mod

Variables

Type Visibility Attributes Name Initial
type(CFIOCollectionVector), public :: collections

Interfaces

public interface ESMF_ioCreate

  • 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

    Type IntentOptional Attributes Name
    type(MAPL_CFIO), intent(out) :: MCFIO
    character(len=*), intent(in) :: NAME
    type(ESMF_Clock), intent(inout) :: CLOCK
    type(ESMF_FIELDBUNDLE), intent(inout) :: BUNDLE
    type(ESMF_TimeInterval), intent(inout), optional :: OFFSET
    type(ESMF_Grid), optional, pointer :: OUTPUT_GRID
    integer, optional, pointer :: CHUNKSIZE(:)
    integer, intent(in), optional :: FREQUENCY
    real, optional, pointer :: LEVELS(:)
    character(len=*), intent(in), optional :: DESCR
    integer, intent(in), optional :: XYOFFSET
    character(len=*), intent(in), optional :: VCOORD
    character(len=*), intent(in), optional :: VUNIT
    real, intent(in), optional :: VSCALE
    character(len=*), intent(in), optional :: source
    character(len=*), intent(in), optional :: institution
    character(len=*), intent(in), optional :: comment
    character(len=*), intent(in), optional :: contact
    character(len=*), intent(in), optional :: format
    character(len=*), intent(in), optional :: EXPID
    integer, intent(in), optional :: DEFLATE
    type(ESMF_GridComp), intent(in), optional :: GC
    integer, intent(in), optional :: Order
    integer, intent(in), optional :: NumCores
    integer, intent(in), optional :: Nbits
    integer, intent(in), optional :: TM
    integer, intent(in), optional :: Conservative
    character(len=*), optional, pointer :: vectorList(:,:)
    type(ESMF_ItemOrder_Flag), intent(in), optional :: itemOrder
    integer, intent(out), optional :: RC
  • 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

    Type IntentOptional Attributes Name
    type(MAPL_CFIO), intent(out) :: MCFIO
    character(len=*), intent(in) :: NAME
    type(ESMF_Clock), intent(inout) :: CLOCK
    type(ESMF_State), intent(inout) :: STATE
    type(ESMF_TimeInterval), intent(inout), optional :: OFFSET
    type(ESMF_Grid), optional, pointer :: OUTPUT_GRID
    integer, optional, pointer :: CHUNKSIZE(:)
    integer, intent(in), optional :: FREQUENCY
    real, optional, pointer :: LEVELS(:)
    character(len=*), intent(in), optional :: DESCR
    type(ESMF_FieldBundle), optional, pointer :: BUNDLE
    integer, intent(in), optional :: XYOFFSET
    character(len=*), intent(in), optional :: VCOORD
    character(len=*), intent(in), optional :: VUNIT
    real, intent(in), optional :: VSCALE
    character(len=*), intent(in), optional :: source
    character(len=*), intent(in), optional :: institution
    character(len=*), intent(in), optional :: comment
    character(len=*), intent(in), optional :: contact
    character(len=*), intent(in), optional :: format
    character(len=*), intent(in), optional :: EXPID
    integer, intent(in), optional :: DEFLATE
    type(ESMF_GridComp), intent(in), optional :: GC
    integer, intent(in), optional :: Order
    integer, intent(in), optional :: NumCores
    integer, intent(in), optional :: Nbits
    integer, intent(in), optional :: TM
    integer, intent(in), optional :: CONSERVATIVE
    integer, intent(out), optional :: RC

public interface ESMF_ioDestroy

  • 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

    Type IntentOptional Attributes Name
    type(MAPL_CFIO), intent(inout) :: MCFIO
    integer, intent(out), optional :: RC

public interface ESMF_ioRead

  • 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

    Type IntentOptional 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
  • 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

    Type IntentOptional 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
  • 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

    Type IntentOptional 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
  • 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

    Type IntentOptional 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
  • 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

    Type IntentOptional 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

public interface ESMF_ioWrite

  • 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

    Type IntentOptional Attributes Name
    type(MAPL_CFIO), intent(inout) :: MCFIO
    type(ESMF_Clock), intent(inout) :: CLOCK
    type(ESMF_State), intent(inout) :: STATE
    logical, intent(in), optional :: VERBOSE
    integer, intent(in), optional :: NBITS
    integer, intent(out), optional :: RC
  • 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

    Type IntentOptional Attributes Name
    type(MAPL_CFIO), intent(inout) :: MCFIO
    type(ESMF_Clock), intent(inout), optional :: CLOCK
    type(ESMF_FIELDBUNDLE), intent(inout), optional :: BUNDLE
    logical, intent(in), optional :: VERBOSE
    integer, intent(in), optional :: NBITS
    logical, intent(in), optional :: created
    integer, intent(out), optional :: RC

public interface MAPL_CFIOCreate

  • 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

    Type IntentOptional Attributes Name
    type(MAPL_CFIO), intent(out) :: MCFIO
    character(len=*), intent(in) :: NAME
    type(ESMF_Clock), intent(inout) :: CLOCK
    type(ESMF_FIELDBUNDLE), intent(inout) :: BUNDLE
    type(ESMF_TimeInterval), intent(inout), optional :: OFFSET
    type(ESMF_Grid), optional, pointer :: OUTPUT_GRID
    integer, optional, pointer :: CHUNKSIZE(:)
    integer, intent(in), optional :: FREQUENCY
    real, optional, pointer :: LEVELS(:)
    character(len=*), intent(in), optional :: DESCR
    integer, intent(in), optional :: XYOFFSET
    character(len=*), intent(in), optional :: VCOORD
    character(len=*), intent(in), optional :: VUNIT
    real, intent(in), optional :: VSCALE
    character(len=*), intent(in), optional :: source
    character(len=*), intent(in), optional :: institution
    character(len=*), intent(in), optional :: comment
    character(len=*), intent(in), optional :: contact
    character(len=*), intent(in), optional :: format
    character(len=*), intent(in), optional :: EXPID
    integer, intent(in), optional :: DEFLATE
    type(ESMF_GridComp), intent(in), optional :: GC
    integer, intent(in), optional :: Order
    integer, intent(in), optional :: NumCores
    integer, intent(in), optional :: Nbits
    integer, intent(in), optional :: TM
    integer, intent(in), optional :: Conservative
    character(len=*), optional, pointer :: vectorList(:,:)
    type(ESMF_ItemOrder_Flag), intent(in), optional :: itemOrder
    integer, intent(out), optional :: RC
  • 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

    Type IntentOptional Attributes Name
    type(MAPL_CFIO), intent(out) :: MCFIO
    character(len=*), intent(in) :: NAME
    type(ESMF_Clock), intent(inout) :: CLOCK
    type(ESMF_State), intent(inout) :: STATE
    type(ESMF_TimeInterval), intent(inout), optional :: OFFSET
    type(ESMF_Grid), optional, pointer :: OUTPUT_GRID
    integer, optional, pointer :: CHUNKSIZE(:)
    integer, intent(in), optional :: FREQUENCY
    real, optional, pointer :: LEVELS(:)
    character(len=*), intent(in), optional :: DESCR
    type(ESMF_FieldBundle), optional, pointer :: BUNDLE
    integer, intent(in), optional :: XYOFFSET
    character(len=*), intent(in), optional :: VCOORD
    character(len=*), intent(in), optional :: VUNIT
    real, intent(in), optional :: VSCALE
    character(len=*), intent(in), optional :: source
    character(len=*), intent(in), optional :: institution
    character(len=*), intent(in), optional :: comment
    character(len=*), intent(in), optional :: contact
    character(len=*), intent(in), optional :: format
    character(len=*), intent(in), optional :: EXPID
    integer, intent(in), optional :: DEFLATE
    type(ESMF_GridComp), intent(in), optional :: GC
    integer, intent(in), optional :: Order
    integer, intent(in), optional :: NumCores
    integer, intent(in), optional :: Nbits
    integer, intent(in), optional :: TM
    integer, intent(in), optional :: CONSERVATIVE
    integer, intent(out), optional :: RC

public interface MAPL_CFIORead

  • 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

    Type IntentOptional 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
  • 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

    Type IntentOptional 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
  • 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

    Type IntentOptional 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
  • 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

    Type IntentOptional 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
  • 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

    Type IntentOptional 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

public interface MAPL_CFIOReadParallel

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

    Arguments

    Type IntentOptional Attributes Name
    type(ESMF_FieldBundle), intent(inout), pointer :: bundlelist(:)
    character(len=*), intent(in) :: filelist(:)
    type(ESMF_Time), intent(inout) :: time
    integer, intent(in), optional :: blocksize
    integer, intent(in), optional :: regridMethod
    logical, intent(in), optional :: gsiMode
    type(ESMF_Time), intent(in), optional :: timelist(:)
    integer, intent(out), optional :: rc

public interface MAPL_CFIOWrite

  • 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

    Type IntentOptional Attributes Name
    type(MAPL_CFIO), intent(inout) :: MCFIO
    type(ESMF_Clock), intent(inout) :: CLOCK
    type(ESMF_State), intent(inout) :: STATE
    logical, intent(in), optional :: VERBOSE
    integer, intent(in), optional :: NBITS
    integer, intent(out), optional :: RC
  • 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

    Type IntentOptional Attributes Name
    type(MAPL_CFIO), intent(inout) :: MCFIO
    type(ESMF_Clock), intent(inout), optional :: CLOCK
    type(ESMF_FIELDBUNDLE), intent(inout), optional :: BUNDLE
    logical, intent(in), optional :: VERBOSE
    integer, intent(in), optional :: NBITS
    logical, intent(in), optional :: created
    integer, intent(out), optional :: RC

Derived Types

type, public ::  MAPL_CFIO


Functions

public function MAPL_CFIOGetFilename(MCFIO)

Arguments

Type IntentOptional Attributes Name
type(MAPL_CFIO), intent(in) :: MCFIO

Return Value character(len=esmf_maxstr)

public function MAPL_CFIOAddCollection(template) result(id)

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: template

Return Value integer

public function MAPL_CFIOIsCreated(MCFIO)

Arguments

Type IntentOptional Attributes Name
type(MAPL_CFIO), intent(in) :: MCFIO

Return Value logical


Subroutines

public subroutine MAPL_CFIOClose(MCFIO, filename, RC)

The subroutine MAPL_CFIOClose only closes the file in MAPL CFIO Object (not a full destroy).

Arguments

Type IntentOptional Attributes Name
type(MAPL_CFIO), intent(inout) :: MCFIO
character(len=*), intent(in), optional :: filename
integer, intent(out), optional :: RC

public subroutine MAPL_CFIOCreateFromFile(MCFIO, BundleIn, RegridMethod, hw, only_vars, RC)

Arguments

Type IntentOptional Attributes Name
type(MAPL_CFIO), intent(inout) :: MCFIO
type(ESMF_FieldBundle), intent(inout), optional :: BundleIn
integer, intent(in), optional :: RegridMethod
integer, intent(in), optional :: hw
character(len=*), intent(in), optional :: only_vars
integer, intent(out), optional :: RC

public subroutine MAPL_CFIOCreatewrite(MCFIO, nsteps, RC)

Arguments

Type IntentOptional Attributes Name
type(MAPL_CFIO), intent(inout) :: MCFIO
integer, intent(in), optional :: nsteps
integer, intent(out), optional :: RC

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

Type IntentOptional Attributes Name
type(MAPL_CFIO), intent(inout) :: MCFIO
integer, intent(out), optional :: RC

public subroutine MAPL_CFIOGet(MCFIO, RootRank, krank, collection_id, RC)

Arguments

Type IntentOptional Attributes Name
type(MAPL_CFIO), intent(inout) :: MCFIO
integer, intent(out), optional :: RootRank
integer, intent(out), optional :: krank
integer, intent(out), optional :: collection_id
integer, intent(out), optional :: RC

public subroutine MAPL_CFIOGetTimeString(MCFIO, Clock, Date, rc)

Arguments

Type IntentOptional Attributes Name
type(MAPL_CFIO), intent(inout) :: MCFIO
type(ESMF_Clock), intent(in) :: Clock
character(len=ESMF_MAXSTR), intent(inout) :: Date
integer, intent(out), optional :: rc

public subroutine MAPL_CFIOOpenWrite(MCFIO, RC)

Arguments

Type IntentOptional Attributes Name
type(MAPL_CFIO), intent(inout) :: MCFIO
integer, intent(out), optional :: RC

public subroutine MAPL_CFIOPartition(Slices, NumColls, NumNodes, Writing, Psize, Root)

Returns Psize and Root, the size (in nodes) and root node of each node partition assigned to active collections.

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: Slices(NumColls)

number of 2-D sections or slices in each collection. The number in inactive collections is ignored.

integer, intent(in) :: NumColls

number of nodes being dealt out to the partitions

integer, intent(in) :: NumNodes

total number of collection, some of which may be inactive

logical, intent(in) :: Writing(NumColls)

identifies active collection

integer, intent(out) :: Psize(NumColls)
integer, intent(out) :: Root(NumColls)

public subroutine MAPL_CFIOReadBundleRead(MCFIO, tindex, hw, RC)

Arguments

Type IntentOptional Attributes Name
type(MAPL_CFIO), intent(inout) :: MCFIO
integer, intent(inout) :: tindex
integer, intent(in), optional :: hw
integer, intent(out), optional :: RC

public subroutine MAPL_CFIOReadBundleWait(MCFIO, RC)

Arguments

Type IntentOptional Attributes Name
type(MAPL_CFIO), intent(inout) :: MCFIO
integer, intent(out), optional :: RC

public subroutine MAPL_CFIOSet(MCFIO, Root, Psize, fName, Krank, IOWorker, globalComm, newFormat, collectionID, fraction, RC)

The subroutine MAPL_CFIOSet sets the member variables of a MAPL CFIO Object.

Arguments

Type IntentOptional Attributes Name
type(MAPL_CFIO), intent(inout) :: MCFIO
integer, intent(in), optional :: Root
integer, intent(in), optional :: Psize
character(len=*), intent(in), optional :: fName
integer, intent(in), optional :: Krank(:)
integer, intent(in), optional :: IOWorker
integer, intent(in), optional :: globalComm
logical, intent(in), optional :: newFormat
integer, intent(in), optional :: collectionID
integer, intent(in), optional :: fraction
integer, intent(out), optional :: RC

public subroutine MAPL_CFIOSetKrank(MCFIO, RC)

Arguments

Type IntentOptional Attributes Name
type(MAPL_CFIO), intent(inout) :: MCFIO
integer, intent(out), optional :: RC

public subroutine MAPL_CFIOWriteBundlePost(MCFIO, PrePost, RC)

The subroutine MAPL_CFIOWriteBundlePost 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.

Read more…

Arguments

Type IntentOptional Attributes Name
type(MAPL_CFIO), intent(inout) :: MCFIO
logical, intent(in), optional :: PrePost
integer, intent(out), optional :: RC

public subroutine MAPL_CFIOWriteBundleWait(MCFIO, CLOCK, RC)

Arguments

Type IntentOptional Attributes Name
type(MAPL_CFIO), intent(inout) :: MCFIO
type(ESMF_Clock), intent(inout) :: CLOCK
integer, intent(out), optional :: RC

public subroutine MAPL_CFIOWriteBundleWrite(MCFIO, CLOCK, RC)

Arguments

Type IntentOptional Attributes Name
type(MAPL_CFIO), intent(inout) :: MCFIO
type(ESMF_Clock), intent(inout) :: CLOCK
integer, intent(out), optional :: RC

public subroutine MAPL_GetCurrentFile(filetmpl, time, filename, rc, EXPID)

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: filetmpl
type(ESMF_Time), intent(inout) :: time
character(len=*), intent(out) :: filename
integer, intent(out), optional :: rc
character(len=*), intent(in), optional :: EXPID