Next: 7 Architectural Overview Up: ESMF_usrdoc Previous: 5 How to Submit Contents

Subsections

6 Quick Start

This section describes how to get the ESMF software, install it, and run a demonstration application. More detailed information about setting up the ESMF, such as how to modify library paths in the makefiles and how to run diagnostic self-tests, can be found in Section 11.

6.1 ESMF Download Options

Major releases of the ESMF software can be downloaded by following the instructions on the the Downloads & Documentation link on the ESMF website, http://www.esmf.ucar.edu.

The ESMF is distributed as a full source code tree. You will need to compile the code into the libesmf.a library. On some platforms a shared library, libesmf.so, is also created. Follow the instructions in the following sections of the Quick Start guide, beginning with Section 6.2, Installation, to build the library and link it with your application.

6.2 Installation

6.2.1 System Requirements

The following compilers and utilities are required for compiling and linking the ESMF software:

a Fortran90 compiler and libraries;
a C++ compiler;
if the C++ compiler is not gcc, a gcc compiler - we need this for a standard cpp preprocessor implementation;
a MPI implementation compatible with these compilers (but see below);
the GNU make utility;
the tar utility, for unpacking data files;
the GNU zip utility, for unpacking data files;
the Perl programming language, for running test scripts.

An alternative to the MPI library is provided with the ESMF, a single-process MPI-bypass library. It allows applications which use MPI to be linked but only run single process.

In order to build html and pdf version of the ESMF documentation, L^ATEX, the latex2html conversion utility, and the Unix/Linux dvipdf utility must be installed.

6.2.2 ESMF Environment Variables

Currently the ESMF_DIR environment variable must be set on all platforms. ESMF_DIR should be set to the path of the top level ESMF directory.

There are several other environment variables that the build system uses. In most cases they do not have to be set by the user. If they are not set, then the build system will assign default values to them. For the current supported platforms, the default values are fine. The other environment variables are:

ESMF_ARCH

Variable that has the value of uname -s. For example, this will be AIX for IBM RS6000's. There should be no reason for the user to set ESMF_ARCH since the proper value should be determined automatically.

ESMF_BOPT

Build option value of g (for debug mode) or O (for optimize mode). Default value will be O.

ESMF_COMM

Defines which MPI communications library to use. Many times a machine will come with its own MPI library and in those cases the default setting will be the native mpi. Otherwise the default setting will be mpiuni so that the mpi stub library will be used. This is the case for Linux and Darwin systems. Other possible settings are mpich and lam.

ESMF_COMPILER

Variable specifying which compiler to use. Value can be default, absoft, intel, lahey, nag, pgi, or xlf. If the value is default or ESMF_COMPILER is left unset, then the default compiler will be used. On systems which usually come with a single vendor-supplied compiler, the default is to use this compiler. On systems like Linux clusters where there is no single vendor compiler installed on all systems, you will generally want to set this. The default for Linux systems is lahey and on Darwin (Mac OS X) systems it is absoft.

ESMF_C_COMPILER

Variable specifying which C/C++ compiler to use. In most cases this should not be set; the default is to use the vendor-supplied compilers on those systems which normally come with a single development environment; on other systems like Linux clusters, the default is to use the ESMF_COMPILER setting. However, some Fortran compilers support linking with C and C++ code compiled with the GNU compilers; in these cases, you can set this variable to the value gnu in order to compile with the vendor Fortran compiler and the GNU C/C++. This option is only supported for ESMF_ARCH=Darwin, ESMF_COMPILER=xlf, and ESMF_ARCH=Linux, ESMF_COMPILER=intel.

ESMF_C_LIBRARY

Variable specifying which C/C++ libraries to link with. In most cases this should not be set; the default is to use the vendor-supplied libraries on those systems which normally come with a single development environment; on other systems like Linux clusters, the default is to use the ESMF_COMPILER setting. However, some vendor compilers support compiling with their compilers but linking with the GNU C/C++ libraries. In these cases, you can set this variable to the value gnu in order to link with the GNU C/C++ libraries. This option is only supported for ESMF_ARCH=Linux, ESMF_COMPILER=intel.

ESMF_EXHAUSTIVE

Variable specifying how to compile the unit tests. If set to the value ON, then all unit tests will be compiled and will be executed when the test is run. If unset or set to any other value, only a subset of the unit tests will be included to verify basic functions. Note that this is a compile-time selection, not a run-time option.

ESMF_NO_IOCODE

This version of the framework is prepared to use the netCDF I/O library. However, because the location of the library and include files varies widely from system to system the support for I/O is disabled by default. To enable support, edit build/common.mk and comment out the two lines which set ESMF_NO_IOCODE to ON and set the CPP flag, and recompile.

ESMF_PREC

Variable specifying the size of an address on systems which can build either 32 or 64 bit executables. When possible the default value will be 64, otherwise it will be 32.

ESMF_SITE

Build configure file site name or the value default. If not set, then the value of default is assumed.

On Alpha machines an additional environment variable needs to be set:

ESMF_PROJECT: Load Sharing Facility (LSF) project name

On an Alpha machine, test and demo applications are run using the bsub command. The value of ESMF_PROJECT is used as the argument for bsub's -P option. The -P option assigns a job to a specific project.

Environment variables must be set in the user's shell and not inside an ESMF makefile or build system file. Here is an example of setting an environment variable in tcsh and csh shells:

  setenv ESMF_PREC 32

In ksh shell environment variables are set this way:

  export ESMF_PREC=32

Environment variables can also be set from the gmake command line:

  gmake ESMF_PREC=32

6.2.3 Supported Platforms

The following two tables list various combinations of environment variable settings used by the ESMF build system. A default value in the compiler column indicates the vendor compiler.

The first table lists the exact combinations which are tested regularly and are fully supported. The second table lists all possible combinations which are included in the build system.

Fully tested combinations:

ESMF_ARCH ESMF_COMPILER ESMF_COMM ESMF_PREC

Alpha OSF1 default mpi 64

Cray X1 Unicos default mpi 64

IBM RS6000 AIX default mpi 32

IBM RS6000 AIX default mpi 64

Linux Linux absoft mpich 32

Linux Linux intel mpich 32

Linux Linux intel lam 64

Linux Linux lahey mpich 32

Linux Linux lahey mpiuni 32

Linux Linux nag mpich 32

Linux Linux pgi mpich 32

Linux Linux pgi mpiuni 32

Mac OS X Darwin absoft lam 32

Mac OS X Darwin absoft mpiuni 32

Mac OS X Darwin xlf lam 32

Mac OS X Darwin xlf mpiuni 32

SGI IRIX64 default mpi 32

SGI IRIX64 default mpi 64

SGI Altix Linux intel mpi 64

All possible options, by platform/compiler. Where multiple options exist, the default value is in bold:

ESMF_ARCH ESMF_COMPILER ESMF_COMM ESMF_PREC

Alpha OSF1 default mpi, mpiuni 64

Cray X1 Unicos default mpi, mpiuni 64

IBM RS6000 AIX default mpi, mpiuni 32, 64

Linux Linux absoft lam, mpich, mpiuni 32

Linux Linux intel lam, mpi, mpich, mpiuni 32, 64

Linux Linux lahey lam, mpich, mpiuni 32

Linux Linux nag lam, mpich, mpiuni 32

Linux Linux pgi lam, mpich, mpiuni 32

Mac OS X Darwin absoft lam, mpich, mpiuni 32

Mac OS X Darwin nag lam, mpich, mpiuni 32

Mac OS X Darwin xlf lam, mpich, mpiuni 32

SGI IRIX64 default mpi, mpiuni 32, 64

SGI Altix Linux intel mpi, mpiuni 64

Simultaneous multiple architecture builds are supported, with one restriction; the test cases may only be run on one platform at a time.

6.2.4 Building the ESMF Libraries

GNU make is required to build the library. On some systems this will be just the command make. On others it might be installed as gmake or even gnumake. In any event, use the -version option with the make command to determine if it is GNU make.

Build the library with the command:

  gmake

  gmake ESMF_BOPT=O

for an optimized version or

  gmake ESMF_BOPT=g

for the debug version.

Build options that enable you to copy the library and *.mod files to specified directories are explained in Section 11.2.

Makefiles throughout the framework are configured to allow users to compile files only in the directory where gmake is entered. Shared libraries are rebuilt only if necessary. In addition the entire ESMF framework may be built from any directory by entering gmake all, assuming that all the environmental variables are set correctly as described in Section 6.2.2.

Users may also run examples or execute unit tests of specific classes by changing directories to the desired class examples or tests directories and entering gmake run_examples or gmake run_tests, respectively. For non-multiprocessor machines, uni-processor targets are available as gmake run_examples_uni or gmake run_tests_uni.

6.2.5 Building the ESMF Documentation

The documentation consists of an ESMF User's Guide, ESMF Requirements Document, and ESMF Reference Manual for Fortran. To build documentation:

  gmake doc              ! Builds the manuals, including pdf and html.

The resulting documentation files will be located in the top level directory $ESMF_DIR/doc.

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

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

6.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 link_rules files found in the following directories:

	$ESMF_DIR/build_config/AIX.default.default
	$ESMF_DIR/build_config/IRIX64.default.default
	$ESMF_DIR/build_config/Linux.intel.default
	$ESMF_DIR/build_config/Linux.lahey.default
	$ESMF_DIR/build_config/Linux.pgi.default
	$ESMF_DIR/build_config/OSF1.default.default

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.blackforest
	AIX.default.bluesky
	Linux.lahey.longs

To build using these makefiles you must set the environment variable ESMF_SITE to blackforest, 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
	ncar - National Center for Atmospheric Research

Users are encouraged to contribute pertinent information to the esmfcontrib respository.

6.4 Demonstration Application

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

6.4.1 Running the Demonstration

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

gmake ESMF_COUPLED_FLOW

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

gmake run_demos_uni

Next: 7 Architectural Overview Up: ESMF_usrdoc Previous: 5 How to Submit Contents

esmf@ucar.edu