external/io_esmf/README.io_esmf

   1 file README.io_esmf
   2 Tom Henderson                                          03/08/07
   3
   4
   5 GENERAL NOTES
   6
   7 This version of WRF has been tested with ESMF 2.2.0rp1 and with ESMF 2.2.2r.
   8 Since ESMF interfaces are still evolving, it is possible that this version of
   9 WRF will not work with newer versions of ESMF.
  10
  11 New environment variables ESMFLIB and ESMFINC may be set to trigger
  12 build using a separately installed ESMF library instead of the default
  13 library embedded in external/esmf_time_f90/.  These new environment variables
  14 must be set to point to library and module paths for the separately
  15 installed ESMF library before WRF "configure" is run.  For example, an
  16 installation of ESMF on bluesky built with default ESMF settings in
  17 /home/bluesky/hender/esmf requires the following settings:
  18   ESMFLIB /home/bluesky/hender/esmf/lib/libO/AIX.default.32.default
  19   ESMFINC /home/bluesky/hender/esmf/mod/modO/AIX.default.32.default
  20 (Note that the portions of the pathnames following
  21 "/home/bluesky/hender/esmf/" are defined by ESMF and described in the ESMF
  22 documentation.)
  23
  24 When ESMFLIB and ESMFINC are set, a new main program is built in
  25 main/wrf_SST_ESMF.exe.  This program is a sample coupled application in
  26 which WRF is coupled to a very simple "data-ocean" component named SST via
  27 a very simple coupler.  While this is a functional example of coupling WRF
  28 to another ESMF component, it should be considered *HIGHLY EXPERIMENTAL*.
  29 The implementation is quite primitive and has severe limitations.
  30 Most important, it is only possible to couple with another component that
  31 uses the exact same grid as WRF due to limitations of ESMF at the time this
  32 work was originally done.  Also, the ESMF component only works with the
  33 DM-Parallel RSL build and has only been tested on AIX.  These and a large
  34 number of other issues are described in external/io_esmf/TODO.list.
  35
  36 Since external/io_esmf is an implementation of the WRF I/O and coupling
  37 API (WRF IOAPI), ESMF coupling can be controlled by the user in the same
  38 manner as other WRF I/O.  Specifically, contents of ESMF import and export
  39 states are defined in the Registry (see Registry.EM_SST for example) and
  40 timing of coupling is defined in namelist.input.  In the case of the WRF-SST
  41 coupling example, the SST component simply reads SST values stored in a file
  42 and sends it to WRF.  Since the SST component also uses the WRF IOAPI and
  43 the format and metadata of SST data files is compatible with the WRF IOAPI,
  44 it is possible to switch from coupled operation to stand-alone operation (in
  45 which WRF reads the SST data directly via auxinput5), simply by changing
  46 the io_form in the namelist.  A test that can be run to validate this claim
  47 can be found in test/em_esmf_exp (see test/em_esmf_exp/README_WRF_CPL_SST.txt).
  48
  49 This is a work-in-progress!
  50
  51
  52 NOTES ABOUT THE EVENT LOOP FOR WRF+CPL+SST
  53
  54 The event loop (time-stepping loop) in the ESMF driver program in
  55 main/wrf_SST_ESMF.F is a serial analog of concurrent coupling performed using
  56 the Model Coupling Environment Library (MCEL) by Michalakes and Bettencourt
  57 (http://www.mmm.ucar.edu/wrf/WG2/Tigers/IOAPI/index.html).  Specifically,
  58 the "read" of the WRF ImportState and the "write" of the WRF ExportState both
  59 occur during subroutine med_before_solve_io() which is called before the main
  60 WRF solver (which advances a domain by one time-step).  This approach is
  61 suitable for "loose" coupling in which precise time synchronization between
  62 components is not critical.  Such "loose" coupling is appropriate for some
  63 ocean-atmosphere systems.  The WRF+CPL+SST event loop contains the following
  64 steps:
  65  - SST run phase 1
  66  - CPL SST to WRF
  67  - CPL WRF to SST
  68  - WRF run
  69  - SST run phase 2
  70 However, coupling of components that require more precise synchronization,
  71 such as land-atmosphere coupling, requires "tighter" coupling.  Also, it is
  72 not always convenient to split a component into multiple run phases (or
  73 multiple components).  A more suitable event loop for this case might contain
  74 the following steps:
  75  - LAND run
  76  - CPL LAND to WRF
  77  - WRF run
  78  - CPL WRF to LAND
  79 This requires modifying WRF so the "output" calls that "write" the WRF
  80 ExportState occur in subroutine med_after_solve_io() in file
  81 share/mediation_integrate.F.
  82 We plan to make this modification in a future revision of WRF and allow users
  83 to control where the WRF ExportState is set at run-time via a namelist
  84 variable.
  85