next up previous contents
Next: 8 Architectural Overview Up: ESMF_usrdoc Previous: 6 Installing and Building   Contents

Subsections


7 Validating and Running with ESMF

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.


7.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 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.

7.1.1 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_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:

${ESMF_DIR}/test/test${ESMF_BOPT}/${ESMF_ARCH}.${ESMF_COMPILER}.${ESMF_PREC}.${ESMF_SITE}

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

       /usr/local/esmf

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:

      build_config/Linux.lahey.default/build_rules.mk

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:

       export ESMF_DIR=/usr/local/esmf

The results of the unit tests will be in:

       /usr/local/esmf/test/testg/Linux.lahey.32.default/

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


7.1.2 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, 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:

${ESMF_DIR}/test/test${ESMF_BOPT}/${ESMF_ARCH}.${ESMF_COMPILER}.${ESMF_PREC}.${ESMF_SITE}

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

       ~/esmf

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:

~/esmf/test/testO/OSF1.default.64.default/ESMF_SimpleCouplingSTest.stdout

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


7.2 Running ESMF Examples

7.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:

        ESMF_DIR/src/Infrastructure/TimeMgr/examples/

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.

7.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:

       ESMF_DIR/examples/examples$ESMF_BOPT/$ESMF_ARCH.$ESMF_COMPILER.$ESMF_PREC.$ESMF_SITE/

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


7.3 Using the ESMF

To use ESMF from Fortran, add the directory that contains the ESMF *.mod file(s),

$ESMF_DIR/mod/mod$ESMF_BOPT/$ESMF_ARCH.$ESMF_COMPILER.$ESMF_PREC.$ESMF_SITE

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:

$ESMF_DIR/lib/lib$ESMF_BOPT/$ESMF_ARCH.$ESMF_COMPILER.$ESMF_PREC.$ESMF_SITE

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.

7.3.1 Shared Object Libraries

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.

7.3.2 Linking

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.

7.3.3 Customized SITE Files

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:

        http://sourceforge.net/projects/esmfcontrib/

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

 	$ESMF_DIR/build_config

and use the following CVS command:

	cvs -z3 -d:ext:$username@cvs.sourceforge.net:/cvsroot/esmfcontrib checkout ncar

The following directories will be checked out:

	AIX.default.bluesky
	Linux.lahey.longs

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.


7.4 Demonstration Application

The ESMF_COUPLED_FLOW demonstration illustrates use of both the ESMF infrastructure and superstructure. It is described in detail in Section 9.

7.4.1 Running the Demonstration

To run the ESMF_COUPLED_FLOW demo starting from ESMF source code, type

gmake ESMF_COUPLED_FLOW
or
gmake ESMF_COUPLED_FLOW_uni
from 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:

gmake run_demos
or
gmake run_demos_uni


next up previous contents
Next: 8 Architectural Overview Up: ESMF_usrdoc Previous: 6 Installing and Building   Contents
esmf@ucar.edu