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 applications. More detailed information on each of these steps is provided in sections 8, 10 and 7, 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 applications as described in sections 6 and 7, respectively.
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
http://sourceforge.net/projects/esmf -> Files
Follow the directions on that web page to download a tar file.
gunzip esmf*.tar.gz
Then untar the file:
tar -xf esmf*.tar
This will create a directory called esmf.
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.
After downloading and unpacking the ESMF tar file, the build procedure is:
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:
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 8 for the full list.
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.
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.
-------------------------------------------------------------- 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 ==============================================================
The makefiles follow the GNU target standards where possible. The most frequently used targets for building are listed below:
To build and run the unit and system tests, type:
gmake checkA summary report of success and failures will be printed out at the end.
See section 10.1.1 on how to set up ESMF to be able to launch the bundled test and example applications.
Other test-related targets are:
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:
For the unit tests only, there is an additional environment variable which affects how the tests are built:
This section describes how the bundled ESMF applications 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 applications, and do not mind the shortcomings of this approach. Users interested in maximum portability should instead follow the instructions provided in section 7.
To build the bundled ESMF applications type:
gmake build_appsThis will build the applications and place the executables under the $ESMF_DIR/apps directory inside the ESMF source tree. The applications 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 applications can be executed by a command equivalent to:
mpirun -np X $(ESMF_DIR)/apps/..../application
where X specifies the total number of PETs and application is the name of the specific ESMF application 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 applications support the standard '--help' command line
option that prints out information on its proper use. More detailed instructions
of the individual applications are available in the "Applications" section of
the ESMF Reference Manual.