8 Using Bundled ESMF Command Line Tools

ESMF comes with a set of bundled command line tools (CLT). 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 CLTs. 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 CLTs. Often access is as simple as loading a configuration module to have the correct path to the ESMF CLT binaries added to your PATH environment variable.

There are two ways a user may choose to build and access the bundled ESMF CLTs. Users that prefer not to go through the full ESMF installation process have the option to build the bundled CLTs 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.3.6 and should only be considered by users that want quick access to the CLTs and are not interested in a sharable installation or the development of portable scripts and makefiles that use the CLTs. Users interested in the latter should consider the more standard second option outlined below.

The bundled ESMF CLTs are built automatically in the process of installing ESMF following the instructions given in section 9.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 CLTs 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 CLT path.

The esmf.mk mechanism used for CLT access is the same as the one described in section 6 for writing robust and portable user makefiles for building and linking user CLTs 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 9.9 for the related discussion aimed at the person that installs ESMF on a system.

Once the exact location of the bundled ESMF CLT 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 CLTs 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 CLTs must be followed. System specific execution details on this level are outside of ESMF's scope. However, ESMF does offer specific CLT 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 CLTs can be executed by a command equivalent to:

mpirun -np X $(ESMF_APPSDIR)/<clt-name>

where X specifies the total number of PETs and clt-name is the name of the specific ESMF command line tool to be executed.

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