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