11 Validating an ESMF Build

The following subsections go into more detail about how to run the tests and examples included with the ESMF software. This is the recommended method of regression testing ESMF, and is routinely used during library code development. Running the regression tests against an existing ESMF installation is also supported, and offers a general way to validate a pre-installed ESMF library.

11.1 Running ESMF Self-Tests

Robustness and portability are primary goals of the ESMF development effort. To ensure that these goals are met, the ESMF includes a comprehensive suite of tests. They allow testing and validation of everything from individual functions to complete system tests. These test suites are used by the ESMF development team as part of their regular development process. ESMF users can run the testing suites to verify that the framework software was built and installed properly, and is running correctly on a particular platform.

11.1.1 Setting up ESMF to run test suite applications

Unless the ESMF library was built in MPI-bypass mode (mpiuni), all applications compiled and linked against ESMF automatically become MPI applications and must be executed as such. The ESMF test suite and example applications are no different in this respect.

Details of how to execute MPI applications vary widely from system to system. ESMF uses an mpirun script mechanism to abstract away most of these differences. All ESMF makefile targets that require the execution of applications do this by launching the application via the executable specified in the ESMF_MPIRUN variable. ESMF assumes that an MPI applications can be launched across N processes by calling

$(ESMF_MPIRUN) -np N application

and that the output of the application arrives at the calling shell via stdout and stderr.

First, on systems that allow direct launching of MPI application via a suitable mpirun facility, ESMF can use it directly. This is the ESMF default for all those configurations that come with a suitable mpirun. In these cases the ESMF_MPIRUN environment variable does not need to be set by the user.

There are systems, however, that allow direct launching of MPI application but provide a launch mechanism that is incompatible with ESMF's assumptions. In these cases a simple mpirun wrapper is required. The ESMF ./scripts directory contains wrappers for several cases in this class, e.g. for interactive POE access on IBM machines and aprun, as well as yod on Cray machines. The ESMF configurations will access the appropriate wrapper scripts by default if necessary.

Secondly, there are those systems that utilize batch software to access the parallel execution environment. One option is to execute the ESMF test targets from within a batch session, either interactively or from within a script. In this case the batch software does not add any additional complexity for ESMF. The same issues discussed above, of how to launch an MPI application, apply directly.

However, in some cases it is more convenient to execute the ESMF test target on the front-end machine, and have ESMF access the batch software each time it needs to launch an application. In fact, on IBM systems this is often the only working option, because the integrated POE system will execute each application on the exact same number of processes specified during batch access, regardless of how many ways in parallel a specific application needs to be run.

Two modes of operation need to be considered in the case of the ESMF batch access. First, if interactive batch access is available, it is straightforward to write an mpirun script that fulfills the ESMF requirements outlined above. The ESMF ./scripts directory contains several scripts that access various parallel launching facilities though interactive LSF.

Second, if interactive batch access is not available, a more complex scripting approach is necessary. The basic requirements in this case are that ESMF must be able to launch MPI applications across N processes by calling

$(ESMF_MPIRUN) -np N application  ,

that the output of the application will be available in a file named application.stdout after the script finishes, and that the ESMF_MPIRUN script blocks execution until application.stdout has become accessible.

The ESMF ./scripts directory contains scripts of this flavor for a wide variety of batch systems. Most of these scripts, when called through ESMF, will generate a customized, temporary batch script for a specific executable "on the fly" and submit this batch script to the queuing software. The script then waits for completion of the submitted job, after which it copies the output, received through a system specific mechanism, into the prescribed file.

Regardless of whether the batch system access is interactive or not, it is often necessary to specify various system specific options when calling the batch submission tool. ESMF utilizes the ESMF_MPIBATCHOPTIONS environment variable to pass user supplied values to the batch system.

The environment variable ESMF_MPISCRIPTOPTIONS is available to pass user specified options to the actual script specified by ESMF_MPIRUN. However, ESMF_MPISCRIPTOPTIONS will only be added automatically to the ESMF_MPIRUN call if the specified ESMF_MPIRUN can be found in the ESMF ./scripts directory.

Finally, the value of ESMF_MPILAUNCHOPTIONS is passed to the MPI launch facility by default, i.e if ESMF_MPIRUN was not specified by the user. In case the user specifies ESMF_MPIRUN to be anything else but scripts out of the ESMF ./scripts directory, it is the user's responsibility to add ESMF_MPISCRIPTOPTIONS to ESMF_MPIRUN and/or to utilize ESMF_MPILAUNCHOPTIONS within the specified script.

The possibilities covered by the generic scripts provided in the ESMF ./scripts directory, combined with the ESMF_MPISCRIPTOPTIONS, ESMF_MPIBATCHOPTIONS, and ESMF_MPILAUNCHOPTIONS environment variables, will satisfy the majority of common situations. There are, however, circumstances for which a customized, user-provided mpirun script is necessary. One such situation arises with the LoadLeveler batch software. LoadLeveler typically requires a list of options specified in the actual batch script. This is most easily handled by a script that produces such a system and user specific script "on the fly". Another situation is where certain modules or software packages need to be made available inside the batch script. Again this is most easily handled by a customized script the user writes and provides to ESMF via the ESMF_MPIRUN environment variable. This will override any default settings for the configuration and rely on the user provided script instead.

Users that face the need to write a customized mpirun script for their parallel execution environment are encouraged to start with the closest match from the ESMF ./scripts directory and customize it to their situation. The best way to see how the existing scripts are used on the supported platforms is to go to the web page and follow the link for the platform of interest. Each test report contains the output of gmake info, which lists the settings of the ESMF_MPIxxx environment variables.

11.1.2 Running ESMF unit tests

The unit tests provided with the ESMF library evaluate the following:

Unit tests can be run in either an exhaustive or a non-exhaustive (sanity check) mode. The exhaustive mode includes the sanity check tests. Typically, sanity checks for each ESMF capability include creating and destroying an object and testing its basic function using a valid argument set. In the exhaustive mode, a wide range of valid and non-valid arguments are evaluated for correct behavior.

The following commands are used to build and run the unit tests provided with the ESMF:

        gmake [ESMF_TESTEXHAUSTIVE=<ON,OFF>] unit_tests
        gmake [ESMF_TESTEXHAUSTIVE=<ON,OFF>] unit_tests_uni

The tests_uni target runs the tests on a single processor. The tests target runs the test on multiple processors.

The non-exhaustive set of unit tests should all pass. At this point in development, the exhaustive tests do not all pass. Current problems with unit tests are being tracked and corrected by the ESMF development team.

The results of running the unit tests can be found in the following location:


For example, if your esmf source files have been placed in:


If your platform is a Linux uni-processor that has an installed Lahey Fortran compiler and ESMF_COMPILER has been set to lahey, then the build system configuration file will be:


If you want to run a debug version of non-exhaustive unit tests, then you use these commands from /usr/local/esmf:

       setenv ESMF_DIR /usr/local/esmf
       gmake ESMF_BOPT=g ESMF_SITE=lahey ESMF_TESTEXHAUSTIVE=OFF tests_uni

If you are using ksh, then replace the setenv command with:

       export ESMF_DIR=/usr/local/esmf

The results of the unit tests will be in:


At the end of unit test execution a script runs to analyze the results.

The script output indicates whether there are any unit test failures. If any unit tests fail, please check if the failures are listed as known bugs in the ESMF release page for your platform and compiler. If the failures are not listed please contact ESMF Support at Please indicate which unit tests are failing, and attach the output of the "gmake info" command to the email.

The script output indicates whether there are any unit test failures. The following is a sample from the script output:

The unit tests in the following files all pass:


The following unit test files failed to build, failed to execute or 
crashed during execution:


The following unit test files had failed unit tests:


The following individual unit tests fail:

  FAIL  DELayout Get Test, ESMF_FRoute8UTest.F90, line 139                                                                                                                                                                                                       
  FAIL  Grid Distribute Test, ESMF_GridCreateUTest.F90, line 198                                                                                                                                                                                                 

The stdout files for the unit tests can be found at:
/home/bluedawn/svasquez/script_dirs/daily_builds/esmf/test/testO/ \

Found 1224 exhaustive multi processor unit tests, 1220 pass and 4 fail.

The following is an example of the output generated when a unit test fails:

ESMF_FieldUTest.stdout: FAIL  Unique default Field names Test, FLD1.5.1 
			& 1.7.1, ESMF_FieldUTest.F90, line 204  Field names 
			not unique

11.1.3 Running ESMF system tests

The system tests provided with the ESMF library evaluate:

The current system test suite includes tests that perform layout reduction operations, redistribution-transpose, halo operations, component creation and intra-grid communication. Some of the system tests are no longer compatible with the current API, but are included in the release for completeness. A complete description of each available system test and its current compatibility status can be found at the ESMF website, The testing and validation page is accessible from the Development link on the navigation bar.

The following commands are used to build and run the system tests:

        gmake [SYSTEM_TEST=xxx] system_tests
        gmake [SYSTEM_TEST=xxx] system_tests_uni

The system_tests_uni target runs the tests on a single processor. The system_tests target runs the test on multiple processors.

If a particular SYSTEM_TEST is not specified, then all available system tests are built and run.

The results of the test can be found in the following location:


For example, if your ESMF source files have been placed in your home directory:


and your platform and compiler configuration is:

       Alpha multi-processor using the native compiler

and you want to run an optimized version of system test SimpleCoupling, then you use these commands from the directory /esmf.

       setenv ESMF_PROJECT <project_name>
       gmake ESMF_DIR=`pwd` SYSTEM_TEST=ESMF_SimpleCoupling system_tests

If you are using ksh then replace the setenv command with this:

       export ESMF_PROJECT=<project_name>

The results will be in:


At the end of system test execution a script runs to analyze the results.

The script output indicates whether there are any system test failures. If any system tests fail, please check if the failures are listed as known bugs in the ESMF release page for your platform and compiler. If the failures are not listed please contact ESMF Support at Please indicate which system tests are failing, and attach the output of the "gmake info" command to the email.

The script output indicates whether there are any system test failures. The following is a sample from the script output:

The following system tests passed:


The following system tests failed, did not build, or did not execute:


The stdout files for the system_tests can be found at:
/home/bluedawn/svasquez/script_dirs/daily_builds/esmf/test/testO/ \

Found 14 system tests, 12 passed and 2 failed.

11.2 Running ESMF Examples

11.2.1 Example source code

Example source code for each class is found in the class's example directory. For example, source code for the Time Manager class examples are found in this directory:


While the example code is formatted to be included in the documentation, it also runs and compiles to ensure accuracy. Examples generally contain simple usage of the basic methods for the class.

11.2.2 Building and running examples

The GNU makefile targets examples and examples_uni build and run programs found in a class's examples directory. After the examples are built, the examples target runs the examples using multiple processors, while examples_uni runs the examples on a single processor.

These targets first build the ESMF library.

Run from ESMF_DIR, this command will build and run all examples on multiple processors:

       gmake examples

If the command is run in an example source code directory, then only the example from that directory will be built and run. The examples and output files are created in this directory:


The name of an output file will begin with the name of the example that created it followed by .stdout.

At the end of examples execution a script runs to analyze the results.

The script output indicates whether there are any example failures. If any examples fail, please check if the failures are listed as known bugs in the ESMF release page for your platform and compiler. If the failures are not listed please contact ESMF Support at Please indicate which examples are failing, and attach the output of the "gmake info" command to the email.

The following is a sample from the script output:

The following examples passed:


The following examples failed, did not build, or did not execute:


The stdout files for the examples can be found at:

Found 34 examples, 32 passed and 2 failed.

11.3 Validating an existing ESMF installation

It is becoming increasingly common to find pre-installed ESMF libraries on professionally maintained HPC systems. Often multiple versions of ESMF are available via environment modules. Before using such a third-party ESMF installation, a user may want ot validate that it is working correctly. System administrators also often need a simple method to re-validate an existing ESMF installation, e.g. after a system update. ESMF offers a simple way to build and run the full regression suite against an existing installation.

A second ESMF source tree is used to run full regression tests against an existing ESMF installation. To support this, the second source tree must be of the exact same version as the ESMF installation to be tested. The two critical environment variables used are ESMF_TESTESMFMKFILE, and ESMFMKFILE. The following bullets outline the procedure:

At this point all of the test targets discussed in sections 11.1 and 11.2 are available. The build targets use the test and example sources under the local (secondary) source tree, but compile and link against the ESMF library pointed to by ESMFMKFILE. A fully functional installation is expected to pass all regression tests.