CESM supports either the default MCT based component interfaces or the ESMF component interfaces. In both cases, the driver and component models remain fundamentally the same.
The ESMF component interface implementation exists in CESM to allow CESM model components to interact with other coupled systems using ESMF coupling standards as well as to support further development and testing of an ESMF driver or ESMF couplers.
In addition, when using the ESMF component interface, if ESMF is compiled with the Xerces XML library, CESM will automatically generate a metadata file using the ESMF attribute capabilities; this XML metadata file provides CIM (Common Information Model) compliant documentation of CESM and the model components. After a CESM case job is completed, a file named, CESM_Component.xml, can be found within the run directory. For more details on ESMF Attributes and the generated XML file, refer to the ESMF Reference Manual section on the Attribute class . For details on the CIM, visit the European Union's METAFOR project site.
The ESMF implementation in CESM1 requires ESMF version 5.2.0p1.
ESMF is NOT required or provided by CESM1. 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. In addition, depending on whether or not you wish to generate XML metadata files using the ESMF attribute functionality, you may also need to download and install the Apache Xerces C++ library; details on using the Xerces library with ESMF are described later in this document.
There are three possible modes of interaction between CESM and ESMF.
No linking to an external ESMF library. CESM uses its own implementation of ESMF timekeeping interfaces (default).
To run with the MCT based component interfaces and the CESM time manager, set the following environment variables
- cd to your case directory - edit env_build.xml - set COMP_INTERFACE to "MCT" - set USE_ESMF_LIB to "FALSE" |
Linking with an ESMF library to use the ESMF time manager but continued use of the MCT based component interfaces.
To run with the MCT based component interfaces and ESMF time manager, set the following environment 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.2.0p1 |
Linking with an ESMF library in order to use ESMF component interfaces and generate the XML metadata file. In this mode ESMF timekeeping is also activated.
To run with the ESMF component interfaces and ESMF time manager, set the following environment 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.2.0p1 |
The ESMF library can be activated in two ways in CESM. The primary way is via the ESMF_LIBDIR environment 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.
When compiling ESMF for CESM with the intent of generating an attributes XML metadata file, the Xerces XML library must be installed and ESMF must be configured to use it. The following environment variables must be set:
Set ESMF_XERCES to "standard"
Set ESMF_XERCES_INCLUDE to the Xerces include directory
Set ESMF_XERCES_LIBPATH to the Xerces library directory
If these environment variables are not set when ESMF is compiled, and CESM is run using the ESMF component interface, error messages will be written to the PET log files indicating that the Xerces library is not available. The CESM run will continue un-hindered, however an XML metadata file will not be generated.
For more detailed instructions on compiling ESMF with the Xerces library, see the ESMF User's Guide section on Building and Installing ESMF and the Xerces third-party library .
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 based and ESMF component 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 setup manually as described above or a CME test can be carried out which is designed to test this exact capability.
The following table contains combinations of CESM/ESMF release versions that are tested and known to work together: