================================================================================
README - ESMF 8.1.0 beta snapshot
Earth System Modeling Framework (ESMF)
Earth System Modeling Framework
Copyright 2002-2020, University Corporation for Atmospheric Research,
Massachusetts Institute of Technology, Geophysical Fluid Dynamics
Laboratory, University of Michigan, National Centers for Environmental
Prediction, Los Alamos National Laboratory, Argonne National Laboratory,
NASA Goddard Space Flight Center.
Licensed under the University of Illinois-NCSA License.
================================================================================
Hello and welcome to ESMF.
If you need to compile and link your code against an already-built ESMF library,
go to the "APPLICATION" section below.
If you need to build the ESMF library, go to the "BUILDING and INSTALLING"
section below. (If you just downloaded the ESMF tarball, it is source code and
you will have to build the library first.)
If you are looking for more documentation, or higher-level information
about the ESMF project itself, go to the "MORE HELP" section below.
Several addon packages are included with this ESMF release under ./src/addon:
ESMPy - Python interface to ESMF.
MAPL - Usability layer developed under the NASA
Modeling Analysis and Prediction (MAP) program.
NUOPC - Interoperability layer developed under the
National Unified Operational Prediction Capability (NUOPC) program.
See each addon package for a specific README file.
Please contact <esmf_support@ucar.edu> with any questions or problems.
================================================================================
================================================================================
APPLICATION compilation and linking
-----------------------------------
If you want to compile and link your application against an ESMF library
which has already been installed on your system, you will need to tell
the compiler where the ESMF module files and ESMF library files are located.
If this has already been documented by the installer of the ESMF library,
follow the directions given. However, if not, then you must determine the
correct compiler and linker flags yourself.
You can do this in a variety of ways. If you already have build scripts or
existing makefiles, you can explicitly add the correct compiler and linker
flags. The ESMF build process puts the modules and library into separate
directories depending on the options used when building the ESMF library.
The directory containing the ESMF library file also contains a makefile
fragment named "esmf.mk" (e.g. ./lib/libg/Linux.intel.32.mpich.default/esmf.mk
for an ESMF library built on Linux with the Intel compiler for 32-bit using
the mpich MPI-implementation). This makefile fragment defines several variables
indicating compiler options, include paths, linker options, library paths and
libraries necessary to compile and link against ESMF with Fortran or C++. Look
at "esmf.mk" to pull out the necessary flags to compile and link your own code
against the installed ESMF library.
Alternatively, you may want to include "esmf.mk" from within your own build
system. All of the variables defined in "esmf.mk" have prefix "ESMF_"
as to prevent name space conflicts with users' makefiles. Notice that "esmf.mk"
is a self-contained file and is not affected by environment variables. It is
not necessary to set any ESMF_ environment variables to use an ESMF library
that has been installed on your system!
================================================================================
================================================================================
BUILDING and INSTALLING the ESMF library
----------------------------------------
The following compilers and utilities are required for compiling, linking and
testing the ESMF software:
* Fortran90 (or later) compiler
* C++ compiler
* GNU's gcc compiler - for a standard cpp preprocessor implementation
* GNU make
* MPI implementation compatible with the above compilers (but see below)
* LAPACK library compatible with the above compilers (but see below)
* Perl - for running test scripts
Alternatively ESMF can be built using a single-processor MPI-bypass library
that comes with ESMF. It allows ESMF applications to be linked and run in
single-process mode.
Steps of the standard build and install procedure:
1) Set required environment variable(s) (see next section below).
2) Type 'gmake' (the GNU make program) to build the ESMF library.
3) Optionally test the ESMF library build using any of the following targets:
a) 'gmake unit_tests' to build and run the unit tests.
b) 'gmake system_tests' to build and run the system tests.
c) 'gmake check' to build and run the unit and system tests.
d) 'gmake examples' to build and run the examples.
f) 'gmake all_tests' to build and run all available tests and examples.
Please consult the "Platform Specific Notes Related to Executing Test
Targets" below before attempting to use any of these targets.
4) Type 'gmake install' to install the ESMF library in a custom location.
5) Optionally test the ESMF library installation via 'gmake installcheck'.
================================================================================
GNUmake
-------
The ESMF build system uses the GNU make program; it is generally named
'gmake' but may also be simply 'make' or 'gnumake' on some platforms. We do
not use configure or autoconf; the selection of various options is done by
setting environment variables before building the framework.
Environment Variables
---------------------
The following environment variables are the most likely ones to be used
for a typical ESMF library build under normal circumstances. In most
situations only one or two environment variables need to be set. There are
other environment variables which can be set to customize the ESMF library
build process. In particular, ESMF's dependency on 3rd party libraries, such as
LAPACK, NETCDF, etc., is controlled by special environment variables. The ESMF
User's Guide documents all environment variables in detail.
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.
bsh/ksh example : export ESMF_DIR=/home/joeuser/esmf
csh/tcsh example : setenv ESMF_DIR /home/joeuser/esmf
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 and ESMF_COMM need not be set. For other
systems (e.g. Linux or Darwin) a multitude of MPI implementations are available
and ESMF_COMM must be set to indicate which implementation is used to build
the ESMF library. Set ESMF_COMM according to your situation to: mpich, mpich2,
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. Please see the User's Guide for more details.
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. Please see the User's Guide for details.
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. Please see the "PORTING" section below for help.
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.
ESMF_OS
Typically equal to the output of "uname -s" except for UNICOS/mp where
ESMF_OS is set to Unicos. This variable is not normally set by the user unless
cross-compiling. ESMF_OS indicates the target system for which the ESMF library
is being built. Under normal circumstances, i.e. ESMF is being built on the
target system, ESMF_OS is set automatically. However, when cross-compiling for
a different target system ESMF_OS must be set to the respective target OS. For
example, when compiling for the Cray X1 on an interactive X1 node ESMF_OS will
be set automatically. However, when ESMF is being cross-compiled for the X1 on
a Linux host the user must set ESMF_OS to Unicos manually in order to indicate
the intended target platform.
ESMF_INSTALL_PREFIX
This variable specifies the prefix of the installation path used with the
install target. Library, F90 module files, header files and documentation
all are installed relative to ESMF_INSTALL_PREFIX by default. See the ESMF
User's Guide on how to customize the installation location of the installed
files using additional "ESMF_INSTALL_..." environment variables.
The ESMF_INSTALL_PREFIX may be provided as an absolute path or relative to
ESMF_DIR.
Supported Makefile Targets
--------------------------
info : print out extensive system configuration information about what
compilers, libraries, paths, flags, etc are being used.
clean : remove all files built for this OS/compiler/ABI.
distclean : remove all files built for all architectures.
clobber : same as distclean.
lib : build the ESMF library only (default).
check : build and run the unit and system tests to validate the library.
all : build the library, the unit and system tests, and examples.
doc : build the documentation (requires specific latex macros packages
and additional utilities). See the ESMF web site for details;
the web site also provides pre-built pdf and html versions of all
docs.
unit_tests : build and run the unit tests
unit_tests_uni : build unit tests and run them in uni-processor mode
build_unit_tests : build unit tests (don't run)
run_unit_tests : run unit tests (don't build)
run_unit_tests_uni : run unit tests in uni-processor mode (don't build)
clean_unit_tests : remove unit test executables only
system_tests : build and run the system tests
system_tests_uni : build system tests and run them in uni-processor mode
build_system_tests : build system tests (don't run)
run_system_tests : run system tests (don't build)
run_system_tests_uni : run system tests in uni-processor mode (don't build)
clean_system_tests : remove system test executables only
examples : build and run the examples
examples_uni : build examples and run them in uni-processor mode
build_examples : build examples (don't run)
run_examples : run examples (don't build)
run_examples_uni : run examples in uni-processor mode (don't build)
clean_examples : remove example executables only
all_tests : build and run all available tests and examples.
build_all_tests : build all available tests and examples (don't run)
run_all_tests : run all available tests and examples (don't build)
clean_all_tests : remove all available test and example executables
install : install the ESMF library in a custom location
installcheck : check the ESMF library installation
Platform Specific Notes Related to Executing Test Targets
---------------------------------------------------------
After the ESMF library has been built successfully it is a good idea to test
its functional integrity by building and executing a range of test applications.
It is important to use the same environment settings for the ESMF gmake test
targets as were used during the library build.
The ESMF library source tree comes with 3 flavors of test codes:
- unit_tests: separately test the functionality of individual ESMF code units
- system_tests: test the interplay of multiple ESMF code units
- examples: demonstrate features of individual ESMF code units. Example
sources are quoted in the ESMF Reference Manual.
Unless the ESMF library was built in MPI-bypass mode (mpiuni), all applications
compiled and linked against ESMF automatically become MPI applications and must
be executed as such. Details of how to execute MPI applications vary widely from
system to system. ESMF uses an mpirun script mechanism to abstract away most of
these differences.
ESMF provides mpirun scripts for a wide range of system configurations. These
are used by ESMF by default or can be set by the user via the ESMF_MPIRUN
environment variable. The best way to see how the existing scripts are used
on the supported platforms is to go to the "Supported Platforms" web page at
https://www.earthsystemcog.org/projects/esmf/platforms_7_0_0 and follow the link
for the platform of interest. Each test report contains the output of
"gmake info", which lists the settings of the ESMF_MPIxxx environment variables.
Users are encouraged to read the "Setting up ESMF to run Test Suite
Applications" in the User's Guide to gain a deeper insight into how ESMF
manages parallel application launching. This User's Guide section is especially
valuable in case no suitable script is available and the user is confronted
with the task of writing a customized, system specific mpirun script to work
with ESMF.
================================================================================
================================================================================
PORTING the ESMF library to a new platform and/or fixing build problems:
-----------------------------------------------------------------------
Overview
--------
If the build_config directory does not already contain a directory for your
platform/compiler, or if your platform/compiler is already supported but you
need to make some adaptations for your local system, this section should help
you get started.
The top level makefile is $ESMF_DIR/makefile. It should not need to be
modified. The bulk of the makefile rules and settings used by all platforms
and compilers is $ESMF_DIR/build/common.mk. This makefile should not be
changed unless the modification is intended to apply to every system on which
ESMF is built. This makefile is included by the top level makefile.
The per-platform makefile fragments which contain the settings which differ
for each system and compiler combination are in separate subdirectories under
$ESMF_DIR/build_config.
If you find the settings are close and you just need to add additional
information, or the changes are very specific to a particular system, you can
set the environment variable ESMF_SITE to a value, and then the makefiles will
include
$ESMF_DIR/build_config/$ESMF_OS.$ESMF_COMPILER.$ESMF_SITE/build_rules.mk,
in addition to the default settings.
If you are supporting a completely new platform, make a new directory
following the naming pattern described below. Copy the contents of the
closest existing match into that directory and start making changes.
Naming Conventions
------------------
In $ESMF_DIR/build_config, each compiler/platform combination has
a separate subdirectory which follows a 3-part naming convention:
The first part is the system name as it is automatically set in ESMF_OS.
The second part is the compiler name for those platforms which support
compilers from different vendors. For those systems which come with a
single vendor-supplied compiler, the compiler name is 'default'.
The environment variable ESMF_COMPILER is used to select the compiler.
The last part of the name is the site-specific information. The 'default'
directories contain files which are always read for the given
architecture/compiler combination. Then, in addition, if the environment
variable ESMF_SITE has a value, the corresponding directory will be
searched after the default directory, for overrides and additional settings
of directory names, values, flags, and other custom information.
Note that building on the SGI Altix is the same as the other Linux/Intel
platforms, so set ESMF_COMPILER to 'intel' to use the files in the
Linux.intel.default directory. For Altix set ESMF_COMM to 'mpi' in order to
pick up the vendor MPI library.
File Descriptions
-----------------
Each default directory contains the following files:
ESMC_Conf.h : C++ preprocessor definitions needed for this platform.
ESMF_Conf.inc : values needed by both preprocessed F90 and C++; contains
information in a format parseable by both languages.
build_rules.mk : makefile fragment which is included by the main ESMF build
system and contains specific settings for this platform.
Customizing an Existing Platform
--------------------------------
0. Check on http://sourceforge.net/projects/esmfcontrib -> CVS to be sure
someone else has not already done this for your location or machine.
1. Set the environment variable ESMF_SITE to a string. Suggested values are
either your location (e.g. mit, cola) or a specific machine (e.g. bluesky).
2. Make a subdirectory named in the form: system.compiler.site
3. Initially copy over only build_rules.mk from the corresponding default
directory and remove all values which remain the same. The build_rules.mk
file in this site-specific directory will be included after the default
one has been read, so only differences should be maintained.
4. The ESMC_Conf.h and ESMF_conf.inc files do not need to be copied.
5. Test and get it working.
6. Post it back on the esmfcontrib sourceforge site for others to use.
Adding a New Platform
---------------------
1. Create a new subdirectory which follows the naming conventions.
2. Copy the contents of the most similar existing directory over to the
new directory.
3. Edit the build_rules.mk file to set the compiler names, flags, etc.
Since ESMF contains both F90 and C++ code, generally the linkers are
not able to simply link without being given additional libraries.
4. Edit the ESMC_Conf.h file and look over the macro definitions.
5. Once it is working, post it back on the esmfcontrib sourceforge site and
email esmf_support@ucar.edu so we can include it in our next
release.
Directories
-----------
build_config: Contains makefile fragments that can be customized by the
user for specific platforms, compilers, and sites.
See the README in this directory for help with porting to
new platforms or compilers.
build: Contains the generic portion of the build that a
user would not be expected to modify. Also contains a
sample user makefile.
scripts: Contains scripts for testing and uniprocessor runs, and some
templates.
src: Contains the source code.
The following directories are created during the building and testing stages:
lib: Contains the ESMF library file.
mod: Contains the Fortran module files.
test: Contains unit and system test executables and output.
examples: Contains examples executables and output.
doc: Contains documentation (if built).
================================================================================
MORE HELP:
---------
Information about the ESMF project can be found at the ESMF web site:
https://www.earthsystemcog.org/
Software documentation for the last public release is at:
https://www.earthsystemcog.org/ -> Users -> User Docs
Software documentation for all releases is at:
https://www.earthsystemcog.org/ -> Software -> Download/Releases
The ESMF User's Guide contains information on building and installing the ESMF.
The ESMF Reference Manual contains information on the architecture of the ESMF,
example code, and details of the API (Application Programming Interface).
The ESMF library source code is also available for download at:
http://sourceforge.net/projects/esmf
Follow the directions on that web page to download a tarball and for
access to the ESMF CVS repository. The Sourceforge site also contains
the bugs, support, and task lists for ESMF.
Demos, system tests, and use test cases, demonstrating how ESMF can be used in
realistic situations are available at:
https://www.earthsystemcog.org/projects/esmf/code_examples/
Contributions from ESMF users are available at:
http://sourceforge.net/projects/esmfcontrib
Please contact esmf_support@ucar.edu with any questions or problems.
================================================================================
$Id$