BASICS: How do I use the ESMF library and ESMF interfaces?

CESM supports use of either the CESM designed component interfaces which are based on MCT datatypes and are used by default in CESM or ESMF compliant component interfaces. In both cases, the driver and component models remain fundamentally the same. The ESMF interface implementation exists in CESM to support further development and testing of an ESMF driver or ESMF couplers and to allow CESM model components to interact with other coupled systems using ESMF coupling standards.

ESMF is NOT required or provided by CESM. It must be downloaded and installed separately. It is safest to compile ESMF and CESM with identical compilers and mpi versions. It may be possible to use versions that are different but compatible; however, it is hard to predict which versions will be compatible and using different versions can result in problems that are difficult to track down.

There are three possible modes of interaction between CESM and ESMF.

1. No linking to an external ESMF library. CESM uses a native implementation of ESMF timekeeping interfaces (default).

   To run with the MCT interfaces and the native time manager, set the following env variables

   - cd to your case directory - edit env_build.xml - set COMP_INTERFACE to "MCT" - set USE_ESMF_LIB to "FALSE"

2. Linking with an ESMF library to use the ESMF time manager but continued use of the native CESM component interfaces.

   To run with the native interfaces and ESMF time manager, set the following env variables

   - cd to your case directory - edit env_build.xml - set COMP_INTERFACE to "MCT" - set USE_ESMF_LIB to "TRUE" - set ESMF_LIBDIR to a valid installation directory of ESMF version 5.3.0

3. Linking with an ESMF library in order to use ESMF component interfaces. In this mode ESMF timekeeping is also activated.

   To run with the ESMF interfaces and ESMF time manager, set the following env variables

   - cd to your case directory - edit env_build.xml - set COMP_INTERFACE to "ESMF" - set USE_ESMF_LIB to "TRUE" - set ESMF_LIBDIR to a valid installation directory of ESMF version 5.3.0

The ESMF library can be activated in two ways in CESM. The primary way is via the ESMF_LIBDIR env variable in the env_build.xml file described above. The secondary way is via a system environment variable called ESMFMKFILE. If this environment variable is set either through a system or module command, then the ESMF library will be picked up by the CESM scripts, but the local CESM variable, ESMF_LIBDIR, will always have precedence.

To verify the correctness of the ESMF component interfaces in CESM, compute and compare CESM global integrals with identical runs differing only in the use of the MCT and ESMF interfaces. In both cases, the ESMF library should be active to guarantee identical time manager values. In both runs, the 'INFO_DBUG' parameter in env_run.xml should be set to 2 which activates the global integral diagnostics. A valid comparison would be a 10 day test from the same initial conditions. The global integrals produced in the cpl log file should be identical in both cases. This test can be set up manually as described above or a CME test can be carried out which is designed to test this exact capability.