This section goes into more detail about how to run the tests which are included with the ESMF software, how to run the examples, demos, and quick_start software, and how to link your own applications with ESMF.
Robustness and portability are primary goals of the ESMF development effort. To ensure that these goals are met, the ESMF includes a comprehesive 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.
Test targets will compile the ESMF library if it has not already been built.
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_EXHAUSTIVE=<ON,OFF>] tests gmake [ESMF_EXHAUSTIVE=<ON,OFF>] 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_EXHAUSTIVE=OFF tests_uni
If you are using ksh, then replace the setenv command with:
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. The following is a sample from the script output:
There are a total of 1224 exhaustive multi processor unit tests, 1220 pass and 4 fail. The unit tests in the following files all pass: src/Infrastructure/Array/tests/ESMF_ArrayUTest.F90 src/Infrastructure/ArrayDataMap/tests/ESMF_ArrayDataMapUTest.F90 src/Infrastructure/Base/tests/ESMF_BaseUTest.F90 src/Infrastructure/Bundle/tests/ESMF_BundleUTest.F90 src/Infrastructure/BundleDataMap/tests/ESMF_BundleDataMapUTest.F90 src/Infrastructure/Config/tests/ESMF_ConfigUTest.F90 src/Infrastructure/DELayout/tests/ESMF_DELayoutUTest.F90 src/Infrastructure/Field/tests/ESMF_FRoute4UTest.F90 src/Infrastructure/Field/tests/ESMF_FieldUTest.F90 src/Infrastructure/FieldComm/tests/ESMF_FieldGatherUTest.F90 src/Infrastructure/FieldDataMap/tests/ESMF_FieldDataMapUTest.F90 src/Infrastructure/Grid/tests/ESMF_GridUTest.F90 src/Infrastructure/IOSpec/tests/ESMF_IOSpecUTest.F90 src/Infrastructure/LocalArray/tests/ESMF_ArrayDataUTest.F90 src/Infrastructure/LocalArray/tests/ESMF_ArrayF90PtrUTest.F90 src/Infrastructure/LocalArray/tests/ESMF_LocalArrayUTest.F90 src/Infrastructure/LogErr/tests/ESMF_LogErrUTest.F90 src/Infrastructure/Regrid/tests/ESMF_Regrid1UTest.F90 src/Infrastructure/Regrid/tests/ESMF_RegridUTest.F90 src/Infrastructure/TimeMgr/tests/ESMF_AlarmUTest.F90 src/Infrastructure/TimeMgr/tests/ESMF_CalRangeUTest.F90 src/Infrastructure/TimeMgr/tests/ESMF_ClockUTest.F90 src/Infrastructure/TimeMgr/tests/ESMF_TimeIntervalUTest.F90 src/Infrastructure/TimeMgr/tests/ESMF_TimeUTest.F90 src/Infrastructure/VM/tests/ESMF_VMBarrierUTest.F90 src/Infrastructure/VM/tests/ESMF_VMBroadcastUTest.F90 src/Infrastructure/VM/tests/ESMF_VMGatherUTest.F90 src/Infrastructure/VM/tests/ESMF_VMScatterUTest.F90 src/Infrastructure/VM/tests/ESMF_VMSendVMRecvUTest.F90 src/Infrastructure/VM/tests/ESMF_VMUTest.F90 src/Superstructure/Component/tests/ESMF_CplCompCreateUTest.F90 src/Superstructure/Component/tests/ESMF_GridCompCreateUTest.F90 src/Superstructure/State/tests/ESMF_StateUTest.F90 The following unit test files failed to build, failed to execute or crashed during execution: src/Infrastructure/TimeMgr/tests/ESMF_CalendarUTest.F90 src/Infrastructure/VM/tests/ESMF_VMSendRecvUTest.F90 The following unit test files had failed unit tests: src/Infrastructure/Field/tests/ESMF_FRoute8UTest.F90 src/Infrastructure/Grid/tests/ESMF_GridCreateUTest.F90 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/AIX.default.64.default
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
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, http://www.esmf.ucar.edu. 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:
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. The following is a sample from the script output:
There are 14 system tests, 12 passed and 2 failed. The following system tests passed: src/system_tests/ESMF_CompCreate/ESMF_CompCreateSTest.F90 src/system_tests/ESMF_FieldExcl/ESMF_FieldExclSTest.F90 src/system_tests/ESMF_FieldHalo/ESMF_FieldHaloSTest.F90 src/system_tests/ESMF_FieldHaloPer/ESMF_FieldHaloPerSTest.F90 src/system_tests/ESMF_FieldRedist/ESMF_FieldRedistSTest.F90 src/system_tests/ESMF_FieldRegrid/ESMF_FieldRegridSTest.F90 src/system_tests/ESMF_FieldRegridMulti/ESMF_FieldRegridMultiSTest.F90 src/system_tests/ESMF_FieldRegridOrder/ESMF_FieldRegridOrderSTest.F90 src/system_tests/ESMF_FlowComp/ESMF_FlowCompSTest.F90 src/system_tests/ESMF_FlowWithCoupling/ESMF_FlowWithCouplingSTest.F90 src/system_tests/ESMF_SimpleCoupling/ESMF_SimpleCouplingSTest.F90 src/system_tests/ESMF_VectorStorage/ESMF_VectorStorageSTest.F90 The following system tests failed, did not build, or did not execute: src/system_tests/ESMF_FieldRegridConserv/ESMF_FieldRegridConsrvSTest.F90 src/system_tests/ESMF_RowReduce/ESMF_RowReduceSTest.F90 The stdout files for the system_tests can be found at: /home/bluedawn/svasquez/script_dirs/daily_builds/esmf/test/testO/AIX.default.64.default
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.
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:
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 examples failures. The following is a sample from the script output:
There are 34 examples, 32 passed and 2 failed. The following examples passed: src/Infrastructure/Array/examples/ESMF_ArrayCreateEx.F90 src/Infrastructure/Array/examples/ESMF_ArrayGetEx.F90 src/Infrastructure/ArrayComm/examples/ESMF_ArrayCommEx.F90 src/Infrastructure/ArrayDataMap/examples/ESMF_ArrayDataMapEx.F90 src/Infrastructure/ArraySpec/examples/ESMF_ArraySpecEx.F90 src/Infrastructure/Bundle/examples/ESMF_BundleCreateEx.F90 src/Infrastructure/BundleDataMap/examples/ESMF_BundleDataMapEx.F90 src/Infrastructure/DELayout/examples/ESMF_DELayoutEx.F90 src/Infrastructure/Field/examples/ESMF_FieldCreateEx.F90 src/Infrastructure/Field/examples/ESMF_FieldFromUserEx.F90 src/Infrastructure/Field/examples/ESMF_FieldGlobalEx.F90 src/Infrastructure/Field/examples/ESMF_FieldWriteEx.F90 src/Infrastructure/FieldComm/examples/ESMF_FieldCommEx.F90 src/Infrastructure/FieldDataMap/examples/ESMF_FieldDataMapEx.F90 src/Infrastructure/LogErr/examples/ESMF_LogErrEx.F90 src/Infrastructure/Regrid/examples/ESMF_RegridEx.F90 src/Infrastructure/Route/examples/ESMF_RouteEx.F90 src/Infrastructure/TimeMgr/examples/ESMF_AlarmEx.F90 src/Infrastructure/TimeMgr/examples/ESMF_CalendarEx.F90 src/Infrastructure/TimeMgr/examples/ESMF_ClockEx.F90 src/Infrastructure/TimeMgr/examples/ESMF_TimeEx.F90 src/Infrastructure/VM/examples/ESMF_VMAllFullReduceEx.F90 src/Infrastructure/VM/examples/ESMF_VMComponentEx.F90 src/Infrastructure/VM/examples/ESMF_VMDefaultBasicsEx.F90 src/Infrastructure/VM/examples/ESMF_VMGetMPICommunicatorEx.F90 src/Infrastructure/VM/examples/ESMF_VMScatterVMGatherEx.F90 src/Infrastructure/VM/examples/ESMF_VMSendVMRecvEx.F90 src/Superstructure/Component/examples/ESMF_AppMainEx.F90 src/Superstructure/Component/examples/ESMF_CplEx.F90 src/Superstructure/Component/examples/ESMF_GCompEx.F90 src/Superstructure/State/examples/ESMF_StateEx.F90 src/Superstructure/State/examples/ESMF_StateReconcileEx.F90 The following examples failed, did not build, or did not execute: src/Infrastructure/Grid/examples/ESMF_GridCreateEx.F90 src/Infrastructure/TimeMgr/examples/ESMF_TimeIntervalEx.F90 The stdout files for the examples can be found at: /home/bluedawn/svasquez/script_dirs/daily_builds/esmf/examples/examplesO/AIX.default.64.default
To use ESMF from Fortran, add the directory that contains the ESMF *.mod file(s),
to your search path for *.mod files. For most compilers this path is identified either with a -I or a -M. You must also link with the ESMF library. For most compilers, adding the -L directory search flag with the following directory:
followed by the -lesmf flag, will link in the ESMF library.
More details of how to link on specific platforms are included in the next section.
There is a single ESMF module, called ESMF_Mod, that should be included in applications with the Fortran USE statement. It is not necessary to include any header files in Fortran.
To use ESMF from C/C++, link with the ESMF library and include the ESMC.h file.
On some platforms, a shared object library is created in addition to the standard .a library. Shared object libraries are libraries that are loaded by the first program that uses them. All programs that start afterwards automatically use the existing shared library. The library is kept in memory as long as any active program is still using it.
Since shared object libraries are pre-linked to system libraries, using them simplifies life for the user when a variety of system libraries are required or when system libraries vary a great deal on a platform-to-platform basis. ESMF requires linking to both Fortran90 and C++ libraries on a set of very non-standardized platforms, and using shared objects helps to hide some of this complexity.
The order in which shared libraries are presented to the linker is important. Library routines must be called before they are defined. So, if a library A uses functionality provided by library B, then library A must appear before library B on the link line.
When building the ESMF libraries on platforms that support both 32 and 64 bit addressing, verify that the ESMF_PREC environment variable is set to match the compile option that was specified to build your application.
To link a Fortran application to the ESMF libraries please refer to the example user makefile, makefile.sample, found in the esmf/build directory. This makefile has been tested on all supported platforms.
In an effort to provide platform specific information for building ESMF and linking the libraries with your application, a SourceForge site, esmfcontrib, has been created. To locate the platform makefiles for a specific institution, check out the build_config_files using the appropriate CVSROOT. The URL for the esmfcontrib SourceForge site is:
Additionally, you may check out all the platform makefile fragments for a particular institution from the esmfcontrib site. For example, to check out the available makefile fragments for platforms at the National Center for Atmospheric Research, ncar, change directories to
and use the following CVS command:
cvs -z3 -d:ext:$firstname.lastname@example.org:/cvsroot/esmfcontrib checkout ncar
The following directories will be checked out:
To build using these makefiles you must set the environment variable ESMF_SITE to bluesky, or longs.
At the present time, we have files for the following institutions:
anl - Argonne National Laboratory cola - Center for Ocean-Land-Atmosphere Studies gsfc - Goddard Space Flight Center mit - Massachusetts Institute of Technology ncar - National Center for Atmospheric Research
Users are encouraged to contribute pertinent information to the esmfcontrib respository.
The ESMF_COUPLED_FLOW demonstration illustrates use of both the ESMF infrastructure and superstructure. It is described in detail in Section 9.
To run the ESMF_COUPLED_FLOW demo starting from ESMF source code, type
gmake ESMF_COUPLED_FLOW_unifrom the $ESMF_DIR directory. This will compile both the ESMF library and the demo and then run the demo.
To simply run the demo, type: