The ECHAM5/NCREGRID-INTERFACE

Patrick Jöckel, Max Planck Institute for Chemistry, Mainz


The ECHAM5/NCREGRID INTERFACE is an essential part of the Modular Earth Submodel System (MESSy) specification.

A) NCREGRID interfaces

NCREGRID provides two interfaces: These interfaces (and the REGRID-namelists) are described in detail in the NCREGRID documentation: ncregrid.pdf.

B) ECHAM5 interface

For the use of NCREGRID from within ECHAM5, some ECHAM5 specific interface routines are provided in messy_ncregrid_tools_e5.f90: In addition, a specialized interface (for tracer initialization) is provided in messy_main_tracer_e5.f90:

B.1) General interface

The SUBROUTINES RGTOOL_E5_READ_NCVAR and RGTOOL_E5_READ_NCFILE are ECHAM5-specific 'wrappers' around the respective NCREGRID high-level interface routines (see A)):
SUBROUTINE RGTOOL_E5_READ_NCVAR( modstr, vname, t, dat&
, lrg, lrgx, lrgy, lrgz, lok & ! OPTIONAL
, hyam, hybm, p0, ps & ! OPTIONAL
, hyai, hybi & ! OPTIONAL
, latm, lonm, lati, loni & ! OPTIONAL
)
CHARACTER(LEN=*),INTENT(IN) :: modstr! name of calling module
CHARACTER(LEN=*),INTENT(IN) :: vname! name of variable to be regridded
INTEGER,INTENT(IN) :: t! netCDF time step
REAL,DIMENSION(:,:,:,:), POINTER :: dat! (local) data field
LOGICAL,INTENT(IN),OPTIONAL :: lrg! regrid (.true.) or scan/import raw data (.false.)
LOGICAL,INTENT(IN), OPTIONAL :: lrgx! regrid in x direction
LOGICAL,INTENT(IN), OPTIONAL :: lrgy! regrid in y direction
LOGICAL,INTENT(IN), OPTIONAL :: lrgz! regrid in z direction
LOGICAL,INTENT(OUT), OPTIONAL :: lok! status flag
REAL, DIMENSION(:), POINTER, OPTIONAL :: hyam! hybrid-A-coefficients (mid-levels)
REAL, DIMENSION(:), POINTER, OPTIONAL :: hybm! hybrid-B-coefficients (mid-levels)
REAL, DIMENSION(:), POINTER, OPTIONAL :: p0! reference pressure
REAL, DIMENSION(:,:), POINTER, OPTIONAL :: ps! (local) surface pressure
REAL, DIMENSION(:), POINTER, OPTIONAL :: hyai! hybrid-A-coefficients (interface-levels)
REAL, DIMENSION(:), POINTER, OPTIONAL :: hybi! hybrid-B-coefficients (interface-levels)
REAL, DIMENSION(:), POINTER, OPTIONAL :: latm! latitude (mid-levels)
REAL, DIMENSION(:), POINTER, OPTIONAL :: lonm! longitude (mid-levels)
REAL, DIMENSION(:), POINTER, OPTIONAL :: lati! latitude (interface-levels)
REAL, DIMENSION(:), POINTER, OPTIONAL :: loni! longitude (interface-levels)

The SUBROUTINE RGTOOL_E5_READ_NCVAR performs the regridding (or raw-data import, if lrg=.false.) of one time step t of the netCDF-variable vname. The data is returned as 4-D array dat(x,z,n,y) of type REAL with dimensions x=longitude, z=level, n=free parameter (e.g., index range for index-fraction-(IXF)-type variables), and y=latitude. Optionally, the underlying grid structure can be retrieved (hyam, hybm, p0, ps hyai, hybi, latm, lonm, lati, loni). Regridding along each dimension (longitude, latitude, level) can be switched off separately, with the optional parameters lrgx, lrgy, and lrgz, respectively. The name of the calling module (modstr) is used to identify the file containing the REGRID-namelist(s): [modstr].nml


SUBROUTINE RGTOOL_E5_READ_NCFILE( modstr, fname, t, dat, vars&
, lrg, lrgx, lrgy, lrgz, lok & ! OPTIONAL
, hyam, hybm, p0, ps & ! OPTIONAL
, hyai, hybi & ! OPTIONAL
, latm, lonm, lati, loni & ! OPTIONAL
)
CHARACTER(LEN=*),INTENT(IN) :: modstr! name of calling module
CHARACTER(LEN=*),INTENT(IN) :: fname! name of netCDF file
INTEGER,INTENT(IN) :: t! netCDF time step
REAL,DIMENSION(:,:,:,:), POINTER :: dat! (local) data field
CHARACTER(LEN=GRD_MAXSTRLEN), DIMENSION(:), POINTER :: vars! variable names
LOGICAL,INTENT(IN),OPTIONAL :: lrg! regrid (.true.) or scan/import raw data (.false.)
LOGICAL,INTENT(IN), OPTIONAL :: lrgx! regrid in x direction
LOGICAL,INTENT(IN), OPTIONAL :: lrgy! regrid in y direction
LOGICAL,INTENT(IN), OPTIONAL :: lrgz! regrid in z direction
LOGICAL,INTENT(OUT), OPTIONAL :: lok! status flag
REAL, DIMENSION(:), POINTER, OPTIONAL :: hyam! hybrid-A-coefficients (mid-levels)
REAL, DIMENSION(:), POINTER, OPTIONAL :: hybm! hybrid-B-coefficients (mid-levels)
REAL, DIMENSION(:), POINTER, OPTIONAL :: p0! reference pressure
REAL, DIMENSION(:,:), POINTER, OPTIONAL :: ps! (local) surface pressure
REAL, DIMENSION(:), POINTER, OPTIONAL :: hyai! hybrid-A-coefficients (interface-levels)
REAL, DIMENSION(:), POINTER, OPTIONAL :: hybi! hybrid-B-coefficients (interface-levels)
REAL, DIMENSION(:), POINTER, OPTIONAL :: latm! latitude (mid-levels)
REAL, DIMENSION(:), POINTER, OPTIONAL :: lonm! longitude (mid-levels)
REAL, DIMENSION(:), POINTER, OPTIONAL :: lati! latitude (interface-levels)
REAL, DIMENSION(:), POINTER, OPTIONAL :: loni! longitude (interface-levels)

The SUBROUTINE RGTOOL_E5_READ_NCFILE performs the regridding (or raw-data import, if lrg=.false.) of one time step t of the netCDF-file fname. The data is returned as 4-D array dat(x,z,m,y) of type REAL with dimensions x=longitude, z=level, m=number of variables, and y=latitude. The variable names are stored in the CHARACTER-array vars. (Note: All variables must be parameter-free, i.e., n=1 !). Optionally, the underlying grid structure can be retrieved (hyam, hybm, p0, ps hyai, hybi, latm, lonm, lati, loni). Regridding along all dimensions (longitude, latitude, level) can be switched off separately, with the optional parameters lrgx, lrgy, and lrgz, respectively. The name of the calling module (modstr) is used to identify the file containing the REGRID-namelist(s): [modstr].nml



B.2) Regridding-trigger events

The module messy_ncregrid_tools_e5.f90 provides further the new fortran-90 type TYPE RGTEVENT ! (regridding-trigger event), which establishes a connection between the ECHAM5 event handler (time control), and the specific requirements for the time control of NCREGRID.
With the variable declaration (global in the module) TYPE(RGTEVENT), DIMENSION(:), POINTER :: RGT the following routine can be called during the initialization phase of the module (e.g., from the respective subroutine called from messy_initialize in messy_main_control_e5.f90) to initialize module-specific regridding-trigger events (max. NMAXRGTE=500 per module) from the RGTEVENTS-namelist in the file [modstr].nml:
SUBROUTINE RGTEVENT_INIT_NML(RGT, modstr)
TYPE (RGTEVENT),DIMENSION(:), POINTER :: RGT! list of regridding trigger events
CHARACTER(LEN=*),INTENT(IN) :: modstr! name of calling module

The syntax of a RGTEVENTS-namelist is

RG_TRIG(index) = ECHAM5-I/O-Event, name, min, step, max, start, action
...

The ECHAM5-I/O-Event comprises 4 fields, like for instance the PUTDATA-entry in the RUNCTL-namelist of ECHAM5. The RGTEVENT is identified in the module code by its name (a string of maximum NCCNTMAXNLEN = 20 characters). The enumeration (index) in the namelist needs not to be continuous (1,2, ...), and the order is not relevant. On the basis of the RGTEVENT-name, it has to be decided in the module code, which subroutine (RGTOOL_E5_READ_NCVAR, or RGTOOL_E5_READ_NCFILE) is used for calling NCREGRID. If RGTOOL_E5_READ_NCVAR is used for RGTEVENT name, the action-string (max. RGTMAXACTSTR = 200 characters) must be the name of a netCDF-variable (after renaming by NCREGRID); if RGTOOL_E5_READ_NCFILE is used for RGTEVENT name, action-string (max. RGTMAXACTSTR = 200 characters) must be a netCDF-filename. In both cases, the first REGRID-namelist in [modstr].nml, which matches the netCDF-variable-name (or netCDF-filename) is used by NCREGRID.


The status of RGTEVENTs can be tested within the ECHAM5 time loop (every time step) with the

SUBROUTINE RGTEVENT_STATUS( status, cpos, rgt, modstr&
, name, index, action, lstop & ! OPTIONAL
)
LOGICAL,INTENT(OUT) :: status! event status
INTEGER,INTENT(OUT) :: cpos! current counter position
TYPE(RGTEVENT),DIMENSION(:), POINTER :: rgt! RGT-event list
CHARACTER(LEN=*),INTENT(IN) :: modstr! name of calling module
CHARACTER(LEN=*),INTENT(IN), OPTIONAL :: name! name of event
INTEGER,INTENT(IN), OPTIONAL :: index! index of event
CHARACTER(LEN=RGTMAXACTSTR),INTENT(OUT), OPTIONAL :: action! action string
LOGICAL,INTENT(IN), OPTIONAL :: lstop! stop on error
The status is .true., if the event occurred at the current ECHAM5 time-step, and .false. otherwise. The position of the counter (between min and max in the RGTEVENTS-namelist) is returned in cpos. The specific event in the list rgt is identified by either its name (as specified in the RGTEVENTS-namelist), or its index (Preferably, the name should be used!). If the requested RGTEVENT (name or index) is not found in the list of events (e.g., due to a typing error in the namelist), ECHAM5 is stopped with an error message (in case lstop=.true.), or ECHAM5 continues with a warning message (in case lstop=.false.). The action-string provides either the netCDF-variable name (for RGTOOL_E5_READ_NCVAR) or the netCDF-filename (for RGTOOL_E5_READ_NCFILE).
The SUBROUTINE RGTEVENT_STATUS does also the complete handling of restart files ([modstr].rst), used for saving the actual counter information.


The ECHAM5-EVENT-NCREGRID interface described so far can be used for the following task:
If the event occurs for the first time during the model run (tested with RGTEVENT_STATUS), NCREGRID regrids/reads the time-step start (RGTEVENTS-namelist) of the netCDF-variable action (if RGTOOL_E5_READ_NCVAR is used in the code for name), or of all variables in the first REGRID-namelist for the netCDF file file (if RGTOOL_E5_READ_NCFILE is used in the code for name). The next time the event occurs (tested with RGTEVENT_STATUS), the time-step (for reading from the netCDF-file) is incremented by step (RGTEVENTS-namelist) before regridding, and so on. After time step max (RGTEVENTS-namelist) is reached, the netCDF-time-step is reset to min (RGTEVENTS-namelist). This allows the cyclic use of time dependent input data.

However, this whole procedure (of event status checking and regridding) within the time loop can be controlled in a much simpler way by using the

SUBROUTINE RGTEVENT_READ( rgt, modstr, name, RGREAD_TYPE, efield&
,lrg, lstop, vars, levent) ! OPTIONAL
TYPE(RGTEVENT),DIMENSION(:), POINTER :: rgt! RGT-event list
CHARACTER(LEN=*),INTENT(IN) :: modstr! name of calling module
CHARACTER(LEN=*),INTENT(IN) :: name! name of RGT-event
INTEGER,INTENT(IN) :: RGREAD_TYPE! RGREAD_NCVAR or RGREAD_NCFILE
REAL, DIMENSION(:,:[,:,:]), INTENT(OUT) :: efield! ECHAM5 data field
LOGICAL,INTENT(IN),OPTIONAL :: lrg! regrid (.true.) or scan/import raw data (.false.)
LOGICAL,INTENT(IN),OPTIONAL :: lstop! stop on error (.true.), default: (.false.)
CHARACTER(LEN=GRD_MAXSTRLEN), DIMENSION(:), POINTER :: vars! variable names
LOGICAL, INTENT(OUT), OPTIONAL :: levent! status of the event

The SUBROUTINE RGTEVENT_READ checks the status of the RGTEVENT with name name in the RGTEVENT list rgt. If the event occurred the restart file ([modstr].rst) with the actual counter information is updated and NCREGRID is started for the event specific data import. The data is returned as 2-, 3-, or 4-dimensional data field efield. The subroutine RGTOOL_E5_READ_NCVAR is used for the data import (1 variable only !), if RGREAD_TYPE = RGREAD_NCVAR. In case RGREAD_TYPE = RGREAD_NCFILE, the subroutine RGTOOL_E5_READ_NCFILE (all data in one netCDF-file) is used instead. In the latter case, the variable names can be returned by the parameter vars. With lrg, regridding can be switched on (.true.), or the raw data can be imported (scan mode, .false.). The optional parameter lstop can be used to force the termination of ECHAM5 (.true.), if a required RGTEVENT is not found in the list rgt. The default (.false.) gives only a warning message. Furthermore, the event status can be returned by the optional parameter levent.


Example 1:


The namelist example.nml of the module 'example' contains the following RGTEVENTS-namelist and REGRID-namelist:
  &RGTEVENTS
  RG_TRIG(1) = 1,'months','first',0,  'OHclim',  1, 1, 12, 3, 'OH',
  RG_TRIG(2) = 1,'months','first',0,  'BOUND',   2, 2, 24, 2, 'bound.nc',
  /
  ®RID
  infile    = "climatological_OH.nc",
  ... (grid specification as described in the NCREGRID documentation)
  var       = "OH=OHc"
  /
  ®RID
  infile    = "bound.nc",
  ... (grid specification as described in the NCREGRID documentation)
  var       = "F1;F2;F3;"
  /
At the beginning of each month, a new time-slice (e.g., monthly averages) of the netCDF-variable OHc should be read into an ECHAM5-variable with name OH. The (cyclic) time-slice counting in the example above starts from 3 (independent on when ECHAM5 starts), goes in steps of 1 up to 12 and starts with 1 again.
Similarly, at the beginnig of each month, the netCDF-time-slices 2, 4, 6, ..., 24, 2, 4, 6, ... etc. of the fields F1, F2, and F3 are imported via NCREGRID from the file bound.nc.
For this, the module messy_example_e5.f90 contains the following code in its global definition section:

  ! USE SPECIAL NCREGRID EVENT TRIGGER
  USE messy_example             ! core-module (e.g., modstr, etc.)
  USE messy_ncregrid_tools_e5,  ONLY: RGTEVENT

  IMPLICIT NONE
  PRIVATE

  ! GLOBAL PARAMETER
  TYPE(RGTEVENT), DIMENSION(:), POINTER  :: RGT

In the initialization routine of messy_example_e5.f90, the RGTEVENTS are initialized with:

  USE messy_ncregrid_tools_e5, ONLY: rgtevent_init_nml

  ...

  CALL rgtevent_init_nml(RGT, modstr)

Within the time loop, the status of the RGTEVENTS is tested and NCREGRID is started with:

  USE messy_ncregrid_tools_e5, ONLY: rgtevent_status       &
                                   , RGTOOL_E5_READ_NCVAR  &
                                   , RGTOOL_E5_READ_NCFILE &
                                   , RGTMAXACTSTR
  USE messy_ncregrid_netcdf,   ONLY: GRD_MAXSTRLEN

  LOGICAL                           :: lev     ! event status
  INTEGER                           :: t       ! netCDF time step
  CHARACTER(LEN=RGTMAXACTSTR)       :: act     ! action
  LOGICAL                           :: lok     ! regridding OK?
  CHARACTER(LEN=GRD_MAXSTRLEN), &
              DIMENSION(:), POINTER :: vars    ! variable names
  REAL, DIMENSION(:,:,:,:), POINTER :: zoh, zf ! data fields

  CALL rgtevent_status(lev, t, RGT, modstr, name='OHclim', action=act)
  IF (lev) THEN
     CALL RGTOOL_E5_READ_NCVAR(modstr, TRIM(act), t, zoh,  &
                               lrg=.true., lok=lok)
     IF (.NOT.lok) THEN
        ! ERROR: REGRIDDING FAILED
     END IF
  END IF
    
  CALL rgtevent_status(lev, t, RGT, modstr, name='BOUND', action=act)
  IF (lev) THEN
     CALL RGTOOL_E5_READ_NCFILE(modstr, TRIM(act), t, zf, vars,  &
                                lrg=.true., lok=lok)
     IF (.NOT.lok) THEN
        ! ERROR: REGRIDDING FAILED
     END IF
  END IF

Note that after successful regridding, SIZE(zf, 3) should be 3 and vars contains the coresponding variable names (F1, F2, F3).


Example 2:


The routine within the time loop of Example 1 can be simplified, if the optional parameters of SUBROUTINE RGTOOL_E5_NCVAR and/or SUBROUTINE RGTOOL_E5_NCFILE are not used:

  USE messy_ncregrid_tools_e5, ONLY: RGTEVENT_READ  &
                                   , RGREAD_NCVAR   &
                                   , RGREAD_NCFILE

  USE messy_ncregrid_netcdf,   ONLY: GRD_MAXSTRLEN

  CHARACTER(LEN=GRD_MAXSTRLEN), &
              DIMENSION(:), POINTER :: vars    ! variable names
  REAL, DIMENSION(:,:,:)            :: zoh
  REAL, DIMENSION(:,:,:,:)          :: zf
  LOGICAL                           :: levent

  ...

  ALLOCATE(ohc(?,?,?),zf(?,?,?,?))

  ...

  CALL RGTEVENT_READ(RGT, modstr, 'OHclim', RGREAD_NCVAR   &
                    ,efield=zoh, lrg=.true., lstop=.false. &
		    ,levent=levent)
  IF (levent) THEN
     ! zoh HAS BEEN UPDATED
  ELSE
     ! zoh IS UNCHANGED
  ENDIF

  CALL RGTEVENT_READ(RGT, modstr, 'BOUND', RGREAD_NCFILE  &
                    ,efield=zf, lrg=.true., lstop=.true.  &
                    ,vars=vars, levent=levent)
  IF (levent) THEN
     ! zf AND vars HAVE BEEN UPDATED
  ELSE
     ! zf AND vars ARE UNCHANGED
  ENDIF

  ...

Notes:
  1. The fields zoh and zf must be allocated with correct size.
  2. The model stops, if the RGTEVENT with name 'BOUND' was not specified in the namelist RGTEVENTS of [modstr].nml, because lstop=.true.



B.3) Tracer initialization

A special routine for the module-specific tracer initialization is provided by messy_main_tracer_e5.f90:
SUBROUTINE TRACER_INIT(modstr)
CHARACTER(LEN=*),INTENT(IN) :: modstr! name of calling module

The name of the calling module (modstr) is used to identify the file containing the REGRID-namelist(s) for the tracer initialization: [modstr]_t.nml



This page was last modified on 28 Apr 2004.
If you have comments or suggestions, e-mail me at joeckel@mpch-mainz.mpg.de  !
You can visit my home-page at http://www.mpch-mainz.mpg.de/~joeckel