Subsections

5 Quick Start

This section gives a brief description of how to get the ESMF software, build it, and run the self-tests to verify the installation was successful. There is also a short guide for using the bundled ESMF command line tools. More detailed information on each of these steps is provided in sections 9, 11 and 8, respectively.

With a growing user community requiring access to ESMF, central computing resources (such as ORNL for the Jaguar and Kraken supercomputers) have recently started providing system wide ESMF installations. The availablity of center-managed ESMF installations dramatically increases the ease of use of ESMF. Practically it means that if you are working on a system (such as Jaguar) that offers a standard ESMF installation, you do not have to download, build and validate your own ESMF installation from source! Instead you can proceed directly to using ESMF as a programming library or through access to the bundled command line tools as described in sections 6 and 8, respectively.

5.1 Downloading ESMF

5.1.1 From the ESMF web site

ESMF is distributed as a source code tar file. The tar file for the latest public release, release notes, known bugs, supported platforms, documentation, and other related information can be found on the ESMF website, under the Download tab:

    http://www.earthsystemmodeling.org -> Download

The source code for all other releases including the HEAD of the CVS trunk and the last stable version can be found by following the View All Releases link on the left hand navigation bar under Download:

    http://www.earthsystemmodeling.org -> Download -> View All Releases

5.1.2 From the SourceForge website

ESMF can also be downloaded from the SourceForge website from the Files link on that website.

    http://sourceforge.net/projects/esmf -> Files

Follow the directions on that web page to download a tar file.

5.2 Unpacking the download

The source code comes as a zipped tar file. First unzip the file:

gunzip esmf*.tar.gz

Then untar the file:

tar -xf esmf*.tar

This will create a directory called esmf.

5.3 Directory Structure

The current list of directories includes the following:

README
build
build_config
makefile
scripts
src

The build_config directory contains subdirectories for different operating system and compiler combinations. This is a useful area to examine if porting ESMF to a new platform.

5.4 Building ESMF

After downloading and unpacking the ESMF tar file, the build procedure is:

Set the required environment variables.
Type gmake info to view and verify your settings
Type gmake to build the library.
Type gmake check to run self-tests to verify the build was successful.

See the following sections for more information on each of these steps.

5.4.1 Environment variables

The syntax for setting environment variables depends on which shell you are running. Examples of the two most common ways to set an environment variable are:

ksh: export ESMF_DIR=/home/joeuser/esmf
csh: setenv ESMF_DIR /home/joeuser/esmf

The shell environment variables listed below are the ones most frequently used. There are others which address needs on specific platforms or are needed under more unusual circumstances; see Section 9 for the full list.

ESMF_DIR

The environment variable ESMF_DIR must be set to the full pathname of the top level ESMF directory before building the framework. This is the only environment variable which is required to be set on all platforms under all conditions.

ESMF_BOPT

This environment variable controls the build option. To make a debuggable version of the library set ESMF_BOPT to g before building. The default is O (capital oh) which builds an optimized version of the library. If ESMF_BOPT is O, ESMF_OPTLEVEL can also be set to a numeric value between 0 and 4 to select a specific optimization level.

ESMF_COMM

On systems with a vendor-supplied MPI communications library, the vendor library is chosen by default for communications. On these systems ESMF_COMM is set to mpi, signaling to the ESMF build system to use the vendor MPI implementation. For other systems (e.g. Linux or Darwin) where a multitude of MPI implementations are available, ESMF_COMM must be set to indicate which implementation is used to build the ESMF library. Set ESMF_COMM according to your situation to: mpt, mpich, mpich1, mpich2, mpich3, mvapich2, lam, openmpi or intelmpi. ESMF_COMM may also be set to user indicating that the user will set all the required flags using advanced ESMF environment variables. Some individual MPI builds may create additional libraries that need to be linked in, such as the legacy C++ bindings. These may be specified via the ESMF_CXXLINKLIBS and ESMF_F90LINKLIBS environment variables.

Alternatively, ESMF comes with a single-processor MPI-bypass library which is the default for Linux and Darwin systems. To force the use of this bypass library set ESMF_COMM equal to mpiuni.

ESMF_COMPILER

The ESMF library build requires a working Fortran90 and C++ compiler. On platforms that don't come with a single vendor supplied compiler suite (e.g. Linux or Darwin) ESMF_COMPILER must be set to select which Fortran and C++ compilers are being used to build the ESMF library. Notice that setting the ESMF_COMPILER variable does not affect how the compiler executables are located on the system. ESMF_COMPILER (together with ESMF_COMM) affect the name that is expected for the compiler executables. Furthermore, the ESMF_COMPILER setting is used to select compiler and linker flags consistent with the compilers indicated.

By default Fortran and C++ compiler executables are expected to be located in a location contained in the user's PATH environment variable. This means that if you cannot locate the correct compiler executable via the which command on the shell prompt the ESMF build system won't find it either!

There are advanced ESMF environment variables that can be used to select specific compiler executables by specifying the full path. This can be used to pick specific compiler executables without having to modify the PATH environment variable.

Use 'gmake info' to see which compiler executables the ESMF build system will be using according to your environment variable settings.

To see possible values for ESMF_COMPILER, cd to $ESMF_DIR/build_config and list the directories there. The first part of each directory name corresponds to the output of 'uname -s' for this platform. The second part contains possible values for ESMF_COMPILER. In some cases multiple combinations of Fortran and C++ compilers are possible, e.g. there is intel and intelgcc available for Linux. Setting ESMF_COMPILER to intel indicates that both Intel Fortran and C++ compilers are used, whereas intelgcc indicates that the Intel Fortran compiler is used in combination with GCC's C++ compiler.

If you do not find a configuration that matches your situation you will need to port ESMF.

ESMF_ABI

If a system supports 32-bit and 64-bit (pointer wordsize) application binary interfaces (ABIs), this variable can be set to select which ABI to use. Valid values are 32 or 64. By default the most common ABI is chosen. On x86_64 architectures three additional, more specific ABI settings are available, x86_64_32, x86_64_small and x86_64_medium.

ESMF_SITE

The SourceForge esmfcontrib repository contains makefiles which have already been customized for certain machines. If one exists for your site and you wish to use it, download the corresponding files into the build_contrib directory and set ESMF_SITE to your location (which corresponds to the last part of the directory name). See the SourceForge site http://sourceforge.net/projects/esmfcontrib for more information.

ESMF_ETCDIR

If a user wants to add Attribute package specification files for their own customized Attribute packages, this is where they should go. ESMF will look in this directory for files that specify which Attributes are in an Attribute package for certain ESMF objects, and what the appropriate initial values would be for those Attributes. The format for these Attribute package specification files is to be defined in a future ESMF release. This environment variable is largely for internal use at this point.

ESMF_INSTALL_PREFIX

This variable specifies the prefix of the installation path used during the installation process accessible thought the install target. Libraries, F90 module files, header files and documentation all are installed relative to ESMF_INSTALL_PREFIX by default. The ESMF_INSTALL_PREFIX may be provided as absolute path or relative to ESMF_DIR.

5.4.2 GNU make

The ESMF build system uses the GNU make program; it is normally named gmake but may also be simply make or gnumake on some platforms (we will use gmake in this document). ESMF does not use configure or autoconf; the selection of various options is done by setting environment variables before building the framework.

5.4.3 gmake info

gmake info is a command that assists the user in verifying that the ESMF variables have been set appropriately. It also tells the user the paths to various libraries e.g. MPI that are set on the system. The user to review this information to verify their settings. In the case of a build failure, this information is invaluable and will be the first thing asked for by the ESMF support team. Below is an example output from gmake info:

--------------------------------------------------------------
Make version:
GNU Make 3.80
Copyright (C) 2002  Free Software Foundation, Inc.
This is free software; see the source for copying conditions.
There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.

--------------------------------------------------------------
Fortran Compiler version:
Intel(R) Fortran Compiler for applications running on Intel(R) 64, \
	Version 10.1    
Build 20081024 Package ID: l_fc_p_10.1.021
Copyright (C) 1985-2008 Intel Corporation.  All rights reserved.

Version 10.1 

--------------------------------------------------------------
C++ Compiler version:
Intel(R) C++ Compiler for applications running on Intel(R) 64, Version 10.1    
Build 20081024 Package ID: l_cc_p_10.1.021
Copyright (C) 1985-2008 Intel Corporation.  All rights reserved.

Version 10.1 

--------------------------------------------------------------
Preprocessor version:
gcc (GCC) 4.1.2 20070115 (SUSE Linux)
Copyright (C) 2006 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.


--------------------------------------------------------------
ESMF_VERSION_STRING:    5.1.0
--------------------------------------------------------------
 
--------------------------------------------------------------
 * User set ESMF environment variables *
ESMF_OS=Linux
ESMF_TESTMPMD=ON
ESMF_TESTHARNESS_ARRAY=RUN_ESMF_TestHarnessArrayUNI_2
ESMF_DIR=/nobackupp10/scvasque/daily_builds/intel/esmf
ESMF_TESTHARNESS_FIELD=RUN_ESMF_TestHarnessFieldUNI_1
ESMF_TESTWITHTHREADS=OFF
ESMF_COMM=mpiuni
ESMF_INSTALL_PREFIX= /nobackupp10/scvasque/daily_builds/intel/esmf/.. \
	/install_dir
ESMF_TESTEXHAUSTIVE=ON
ESMF_BOPT=g
ESMF_SITE=default
ESMF_ABI=64
ESMF_COMPILER=intel
 
--------------------------------------------------------------
 * ESMF environment variables *
ESMF_DIR: /nobackupp10/scvasque/daily_builds/intel/esmf
ESMF_OS:                Linux
ESMF_MACHINE:           x86_64
ESMF_ABI:               64
ESMF_COMPILER:          intel
ESMF_BOPT:              g
ESMF_COMM:              mpiuni
ESMF_SITE:              default
ESMF_PTHREADS:          ON
ESMF_OPENMP:            ON
ESMF_ARRAY_LITE:        FALSE
ESMF_NO_INTEGER_1_BYTE: FALSE
ESMF_NO_INTEGER_2_BYTE: FALSE
ESMF_FORTRANSYMBOLS:    default
ESMF_DEFER_LIB_BUILD:   ON
ESMF_TESTEXHAUSTIVE:    ON
ESMF_TESTWITHTHREADS:   OFF
ESMF_TESTMPMD:          ON
ESMF_TESTSHAREDOBJ:     OFF
ESMF_TESTFORCEOPENMP:   OFF
ESMF_TESTHARNESS_ARRAY: RUN_ESMF_TestHarnessArrayUNI_2
ESMF_TESTHARNESS_FIELD: RUN_ESMF_TestHarnessFieldUNI_1
ESMF_MPIRUN:            /nobackupp10/scvasque/daily_builds/intel/esmf/src/ \
                         Infrastructure/stubs/mpiuni/mpirun
 
--------------------------------------------------------------
 * ESMF environment variables pointing to 3rd party software *
 
--------------------------------------------------------------
 * ESMF environment variables for final installation *
ESMF_INSTALL_PREFIX:    /nobackupp10/scvasque/daily_builds/intel/esmf/../ \
	install_dir
ESMF_INSTALL_HEADERDIR: include
ESMF_INSTALL_MODDIR:    mod/modg/Linux.intel.64.mpiuni.default
ESMF_INSTALL_LIBDIR:    lib/libg/Linux.intel.64.mpiuni.default
ESMF_INSTALL_BINDIR:    bin/bing/Linux.intel.64.mpiuni.default
ESMF_INSTALL_DOCDIR:    doc
 
 
--------------------------------------------------------------
 * Compilers, Linkers, Flags, and Libraries *
Location of the preprocessor:      /usr/bin/gcc
Location of the Fortran compiler:  /nasa/intel/fce/10.1.021/bin/ifort
Location of the Fortran linker:    /nasa/intel/fce/10.1.021/bin/ifort
Location of the C++ compiler:      /nasa/intel/cce/10.1.021/bin/icpc
Location of the C++ linker:        /nasa/intel/cce/10.1.021/bin/icpc

Fortran compiler flags:
ESMF_F90COMPILEOPTS: -g -fPIC -m64 -mcmodel=small -threads  -openmp
ESMF_F90COMPILEPATHS: -I/nobackupp10/scvasque/daily_builds/intel/esmf/mod/ \
	modg/Linux.intel.64.mpiuni.default -I/nobackupp10/scvasque/daily_builds \
	/intel/esmf/src/include 
ESMF_F90COMPILECPPFLAGS: -DESMF_TESTEXHAUSTIVE -DSx86_64_small=1 \
	-DESMF_OS_Linux=1  -DESMF_MPIUNI
ESMF_F90COMPILEFREECPP: 
ESMF_F90COMPILEFREENOCPP: 
ESMF_F90COMPILEFIXCPP: 
ESMF_F90COMPILEFIXNOCPP: 

Fortran linker flags:
ESMF_F90LINKOPTS:  -m64 -mcmodel=small -threads  -openmp
ESMF_F90LINKPATHS: -L/nobackupp10/scvasque/daily_builds/intel/esmf/lib/libg/ \
	Linux.intel.64.mpiuni.default  -L/nasa/sgi/mpt/1.25/lib -L/nasa/intel/ \
	cce/10.1.021/lib/shared -L/nasa/intel/fce/10.1.021/lib/shared -L/nasa/ \
	intel/cce/10.1.021/lib -L/nasa/intel/fce/10.1.021/lib -L/nasa/intel/cce/ \
	10.1.021/lib -L/usr/lib64/gcc/x86_64-suse-linux/4.1.2/ -L/usr/lib64/gcc/ \
	x86_64-suse-linux/4.1.2/../../../../lib64
ESMF_F90LINKRPATHS: 
	-Wl,-rpath,/nobackupp10/scvasque/daily_builds/intel/esmf/lib/libg/ \
	Linux.intel.64.mpiuni.default
ESMF_F90LINKLIBS:  -limf -lsvml -lm -lipgo -lguide -lstdc++ -lirc -lgcc_s \
	-lgcc -lirc -lpthread -lgcc_s -lgcc -lirc_s -ldl -lrt -ldl
ESMF_F90ESMFLINKLIBS: -lesmf  -limf -lsvml -lm -lipgo -lguide -lstdc++ -lirc \
	-lgcc_s -lgcc -lirc -lpthread -lgcc_s -lgcc -lirc_s -ldl -lrt -ldl

C++ compiler flags:
ESMF_CXXCOMPILEOPTS: -g -fPIC -m64 -mcmodel=small -pthread  -openmp
ESMF_CXXCOMPILEPATHS: -I/nobackupp10/scvasque/daily_builds/intel/ esmf/src/ \
	include  -I/nobackupp10/scvasque/daily_builds/intel/esmf/src/Infrastructure \
	/stubs/mpiuni
ESMF_CXXCOMPILECPPFLAGS: -DESMF_TESTEXHAUSTIVE  -DSx86_64_small=1 \
	-DESMF_OS_Linux=1 -D__SDIR__=” -DESMF_MPIUNI

C++ linker flags:
ESMF_CXXLINKOPTS:  -m64 -mcmodel=small -pthread  -openmp
ESMF_CXXLINKPATHS: -L/nobackupp10/scvasque/daily_builds/intel/esmf/lib/libg/ \
	Linux.intel.64.mpiuni.default  -L/nasa/intel/fce/10.1.021/lib/
ESMF_CXXLINKRPATHS: -Wl,-rpath,/nobackupp10/scvasque/daily_builds/intel/esmf/ \
	lib/libg/Linux.intel.64.mpiuni.default -Wl,-rpath,/nasa/intel/fce/ \
	10.1.021/lib/
ESMF_CXXLINKLIBS:  -lifport -lifcoremt -limf -lsvml -lm -lipgo -lguide -lirc \
	-lpthread -lgcc_s -lgcc -lirc_s -ldl -lrt -ldl
ESMF_CXXESMFLINKLIBS: -lesmf  -lifport -lifcoremt -limf -lsvml -lm -lipgo \
	-lguide -lirc -lpthread -lgcc_s -lgcc -lirc_s -ldl -lrt -ldl


--------------------------------------------------------------
Compiling on Thu Oct 21 02:15:56 PDT 2010 on r75i0n8
Machine characteristics: Linux r75i0n8 2.6.16.60-0.68.1.20100916-nasa \
	#1 SMP Fri 
Sep 17 17:49:05 UTC 2010 x86_64 x86_64 x86_64 GNU/Linux
==============================================================

5.4.4 Building makefile targets

The makefiles follow the GNU target standards where possible. The most frequently used targets for building are listed below:

lib: build the ESMF libraries only (default)
all: build the libraries, unit and system tests and examples
doc: build the documentation (requires specific latex macros packages and additional utilities; see Section 9 for more details on the requirements).
info: print out extensive system configuration information about what compilers, libraries, paths, flags, etc are being used
clean: remove all files built for this platform/compiler/wordsize.
clobber: remove all files built for all architectures
install: install the ESMF library in a custom location

5.4.5 Testing makefile targets

To build and run the unit and system tests, type:

gmake check

A summary report of success and failures will be printed out at the end.

See section 11.1.1 on how to set up ESMF to be able to launch the bundled test and example applications.

Other test-related targets are:

all_tests: build and run all available tests and examples
build_all_tests: build tests and examples; do not execute
run_all_tests: run tests and examples without rebuilding; print a summary of the results
check_all_tests: print out the results summary without re-executing
dust_all_tests: remove all test and example output files
clean_all_tests: remove all test and example executables and output files

For all the targets listed above, the string all_tests can be replaced with one of the strings listed below to select a specific type of test:

unit_tests: unit tests exercise a single part of the system
system_tests: system tests combine functions across the system
examples: examples contain code illustrating a single type of function

For example, gmake build_examples recompiles the example programs but does not execute them. gmake dust_unit_tests removes all output files generated when executing the unit tests, but leaves the executables. gmake clean_system_tests removes all executables and files associated with the system tests.

For the unit tests only, there is an additional environment variable which affects how the tests are built:

ESMF_TESTEXHAUSTIVE: If this variable is set to ON before compiling the unit tests, longer and more exhaustive unit tests will be run. Note that this is a compile-time and not run-time option.

5.4.6 Building and using bundled ESMF Command Line Tools

This section describes how the bundled ESMF command line tools can be built and used from inside the ESMF source tree. Notice that this is sort of a quick and dirty way of accessing the ESMF applications. It is supported as convenience to those users interested in quickly gaining access to the bundled ESMF command line tools, and do not mind the shortcomings of this approach. Users interested in maximum portability should instead follow the instructions provided in section 8.

To build the bundled ESMF command line tools, type:

gmake build_apps

This will build the command line tools and place the executables under the $ESMF_DIR/apps directory inside the ESMF source tree. The command line tools can be directly executed from within the $ESMF_DIR/apps directory 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.

For most systems, the MPI version of the ESMF bundled command line tools can be executed by a command equivalent to:

mpirun -np X $(ESMF_DIR)/apps/..../<cli-name>

where X specifies the total number of PETs and cli-name is the name of the specific ESMF command line tool to be executed. The .... in the path indicates the precise subdirectory structure under ./apps which follows the standard ESMF pattern also used for the ./tests and ./examples subdirectories.

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

esmf_support@ucar.edu