file README.io_esmf
Tom Henderson                                          10/10/06

This version of WRF has been tested with ESMF 2.2.0rp1.  Since ESMF interfaces 
are still changing with each new release, it is quite likely that this version 
of WRF will not work with other versions of ESMF.  

NOTE:  ESMF 3.0.0 is available at the time of this writing.  However, 
       ESMF 3.0.0 fails to build with IBM's xlf 10.1 compiler.  (The ESMF core 
       team expects this problem to be resolved by a later release of xlf.)  
       Therefore WRF was not tested with ESMF 3.0.0.  

New environment variables ESMFLIB and ESMFINC may be set to trigger 
build using a separately installed ESMF library instead of the default 
library embedded in external/esmf_time_f90/.  These new environment variables 
must be set to point to library and module paths for the separately 
installed ESMF library before WRF "configure" is run.  For example, an 
installation of ESMF on bluesky built with default ESMF settings in 
/home/bluesky/hender/esmf requires the following settings:  
  ESMFLIB /home/bluesky/hender/esmf/lib/libO/AIX.default.32.default
  ESMFINC /home/bluesky/hender/esmf/mod/modO/AIX.default.32.default
(Note that the portions of the pathnames following 
"/home/bluesky/hender/esmf/" are defined by ESMF and described in the ESMF 
documentation.)  

When ESMFLIB and ESMFINC are set, a new main program is built in 
main/wrf_SST_ESMF.exe.  This program is a sample coupled application in 
which WRF is coupled to a very simple "data-ocean" component named SST via 
a very simple coupler.  While this is a functional example of coupling WRF 
to another ESMF component, it should be considered *HIGHLY EXPERIMENTAL*.  
The implementation is quite primitive and has severe limitations.  
Most important, it is only possible to couple with another component that 
uses the exact same grid as WRF due to limitations of ESMF at the time this 
work was done.  Also, the ESMF component only works with the DM-Parallel RSL 
build and has only been tested on AIX.  These and a large number of other 
issues are described in external/io_esmf/TODO.list.  

Since external/io_esmf is an implementation of the WRF I/O and coupling 
API (WRF IOAPI), ESMF coupling can be controlled by the user in the same 
manner as other WRF I/O.  Specifically, contents of ESMF import and export 
states are defined in the Registry (see Registry.EM_SST for example) and 
timing of coupling is defined in namelist.input.  In the case of the WRF-SST 
coupling example, the SST component simply reads SST values stored in a file 
and sends it to WRF.  Since the SST component also uses the WRF IOAPI and 
the format and metadata of SST data files is compatible with the WRF IOAPI, 
it is possible to switch from coupled operation to stand-alone operation (in 
which WRF reads the SST data directly via auxinput5), simply by changing 
the io_form in the namelist.  

This is a work-in-progress!