7 Using Bundled ESMF Applications

ESMF comes with a set of bundled applications in the form of standard command line tools. These applications include convenient access to general information about an ESMF installation, and regrid weight file generation (sometimes referred to as "offline" regridding). This section provides assistance with respect to building and running the bundled applications. If you are using a pre-installed ESMF on your system, follow the local instructions provided by the installer or system admin of how to access and run the ESMF applications. Often access is as simple as loading a configuration module to have the correct path to the ESMF application binaries added to your PATH environment variable.

There are two ways a user may choose to build and access the bundled ESMF applications. Users that prefer not to go through the full ESMF installation process have the option to build the bundled applications inside of the ESMF source tree, very similar to how the unit tests, system tests and examples are built. This option is outlined in section 5.4.6 and should only be considered by users that want quick access to the applications and are not interested in a sharable installation or the development of portable scripts and makefiles that use the applications. Users interested in the latter should consider the more standard second option outlined below.

The bundled ESMF applications are built automatically in the process of installing ESMF following the instructions given in section 8.9. On systems that offer system-wide ESMF installations (e.g. via modules or similar mechanisms) the user need not worry about the build and installation details. Once installed, the applications are accessible through their precise location on the system. For this purpose every ESMF installation provides a file named esmf.mk that contains the variable ESMF_APPSDIR which specifies the precise application path.

The esmf.mk mechanism used for application access is the same as the one described in section 6 for writing robust and portable user makefiles for building and linking user applications against an ESMF installation. One feature of the esmf.mk mechanism is that only one single piece of information must be known about an ESMF installation to use it, and that is the location of file esmf.mk itself. The location of this file should be documented by the party that installed ESMF on the system. We recommend that a single ESMF specific environment variable ESMFMKFILE be provided by the system that points to the esmf.mk file. See section 8.9 for the related discussion aimed at the person that installs ESMF on a system.

Once the exact location of the bundled ESMF application files has been determined, either by inspecting the associated esmf.mk file, or by using the ESMF_APPSDIR makefile variable directly in the user script or makefile, the applications can be executed following the system specific rules for execution. The details will depend on whether ESMF was built with or without MPI dependency. In the latter case the system specific rules for launching parallel applications must be followed. System specific execution details on this level are outside of ESMF's scope. However, ESMF does offer specific application use examples as part of the external_demos module described online at the External Demos webpage. For most systems, the MPI version of the ESMF bundled applications can be executed by a command equivalent to:

mpirun -np X $(ESMF_APPSDIR)/application

where X specifies the total number of PETs and application is the name of the specific ESMF application to be executed.

All bundled ESMF applications support the standard '--help' command line option that prints out information on its proper use. More detailed instructions of the individual applications are available in the "Applications" section of the ESMF Reference Manual.