next up previous contents
Next: 2 Applications Up: ESMF_refdoc Previous: Contents   Contents

Subsections

1 ESMF Overview

1 What is the Earth System Modeling Framework?

The Earth System Modeling Framework (ESMF) is a suite of software tools for developing high-performance, multi-component Earth science modeling applications. Such applications may include a few or dozens of components representing atmospheric, oceanic, terrestrial, or other physical domains, and their constituent processes (dynamical, chemical, biological, etc.). Often these components are developed by different groups independently, and must be ``coupled'' together using software that transfers and transforms data among the components in order to form functional simulations.

ESMF supports the development of these complex applications in a number of ways. It introduces a set of simple, consistent component interfaces that apply to all types of components, including couplers themselves. These interfaces expose in an obvious way the inputs and outputs of each component. It offers a variety of data structures for transferring data between components, and libraries for regridding, time advancement, and other common modeling functions. Finally, it provides a growing set of tools for using metadata to describe components and their input and output fields. This capability is important because components that are self-describing can be integrated more easily into automated workflows, model and dataset distribution and analysis portals, and other emerging ``semantically enabled'' computational environments.

ESMF is not a single Earth system model into which all components must fit, and its distribution doesn't contain any scientific code. Rather it provides a way of structuring components so that they can be used in many different user-written applications and contexts with minimal code modification, and so they can be coupled together in new configurations with relative ease. The idea is to create many components across a broad community, and so to encourage new collaborations and combinations.

ESMF offers the flexibility needed by this diverse user base. It is tested nightly on more than two dozen platform/compiler combinations; can be run on one processor or thousands; supports shared and distributed memory programming models and a hybrid model; can run components sequentially (on all the same processors) or concurrently (on mutually exclusive processors); and supports single executable or multiple executable modes.

ESMF's generality and breadth of function can make it daunting for the novice user. To help users navigate the software, we try to apply consistent names and behavior throughout and to provide many examples. The large-scale structure of the software is straightforward. The utilities and data structures for building modeling components are called the ESMF infrastructure. The coupling interfaces and drivers are called the superstructure. User code sits between these two layers, making calls to the infrastructure libraries underneath and being scheduled and synchronized by the superstructure above. The configuration resembles a sandwich, as shown in Figure 1.

ESMF users may choose to extensively rewrite their codes to take advantage of the ESMF infrastructure, or they may decide to simply wrap their components in the ESMF superstructure in order to utilize framework coupling services. Either way, we encourage users to contact our support team if questions arise about how to best use the software, or how to structure their application. ESMF is more than software; it's a group of people dedicated to realizing the vision of a collaborative model development community that spans insitutional and national bounds.

2 The ESMF Reference Manual for Fortran

ESMF has a complete set of Fortran interfaces and some C interfaces. This ESMF Reference Manual is a listing of ESMF interfaces for Fortran.1

Interfaces are grouped by class. A class is comprised of the data and methods for a specific concept like a physical field. Superstructure classes are listed first in this Manual, followed by infrastructure classes.

The major classes in the ESMF superstructure are Components, which usually represent large pieces of functionality such as atmosphere and ocean models, and States, which are the data structures used to transfer data between Components. There are both data structures and utilities in the ESMF infrastructure. Data structures include multi-dimensional Arrays, Fields that are comprised of an Array and a Grid, and collections of Arrays and Fields called ArrayBundles and FieldBundles, respectively. There are utility libraries for data decomposition and communications, time management, logging and error handling, and application configuration.

Figure 1: Schematic of the ESMF ``sandwich'' architecture. The framework consists of two parts, an upper level superstructure layer and a lower level infrastructure layer. User code is sandwiched between these two layers.
\scalebox{1.0}{\includegraphics{ESMF_sandwich}}


3 How to Contact User Support and Find Additional Information

The ESMF team can answer questions about the interfaces presented in this document. For user support, please contact esmf_support@list.woc.noaa.gov.

The website, http://www.earthsystemmodeling.org, provide more information of the ESMF project as a whole. The website includes release notes and known bugs for each version of the framework, supported platforms, project history, values, and metrics, related projects, the ESMF management structure, and more. The ESMF User's Guide contains build and installation instructions, an overview of the ESMF system and a description of how its classes interrelate (this version of the document corresponds to the last public version of the framework). Also available on the ESMF website is the ESMF Developer's Guide that details ESMF procedures and conventions.


4 How to Submit Comments, Bug Reports, and Feature Requests

We welcome input on any aspect of the ESMF project. Send questions and comments to esmf_support@list.woc.noaa.gov.


5 Conventions

5.1 Typeface and Diagram Conventions

The following conventions for fonts and capitalization are used in this and other ESMF documents.

Style Meaning Example
italics documents ESMF Reference Manual
courier code fragments ESMF_TRUE
courier() ESMF method name ESMF_FieldGet()
boldface first definitions An address space is ...
boldface web links and tabs Developers tab on the website
Capitals ESMF class name DataMap

ESMF class names frequently coincide with words commonly used within the Earth system domain (field, grid, component, array, etc.) The convention we adopt in this manual is that if a word is used in the context of an ESMF class name it is capitalized, and if the word is used in a more general context it remains in lower case. We would write, for example, that an ESMF Field class represents a physical field.

Diagrams are drawn using the Unified Modeling Language (UML). UML is a visual tool that can illustrate the structure of classes, define relationships between classes, and describe sequences of actions. A reader interested in more detail can refer to a text such as The Unified Modeling Language Reference Manual. [21]

5.2 Method Name and Argument Conventions

Method names begin with ESMF_, followed by the class name, followed by the name of the operation being performed. Each new word is capitalized. Although Fortran interfaces are not case-sensitive, we use case to help parse multi-word names.

For method arguments that are multi-word, the first word is lower case and subsequent words begin with upper case. ESMF class names (including typed flags) are an exception. When multi-word class names appear in argument lists, all letters after the first are lower case. The first letter is lower case if the class is the first word in the argument and upper case otherwise. For example, in an argument list the DELayout class name may appear as delayout or srcDelayout.

Most Fortran calls in the ESMF are subroutines, with any returned values passed through the interface. For the sake of convenience, some ESMF calls are written as functions.

A typical ESMF call looks like this:

call ESMF_<ClassName><Operation>(classname, firstArgument, 
           secondArgument, ..., rc)

where
<ClassName> is the class name,
<Operation> is the name of the action to be performed,
classname is a variable of the derived type associated with the class,
the arg* arguments are whatever other variables are required for the operation,
and rc is a return code.

6 The ESMF Application Programming Interface

The ESMF Application Programming Interface (API) is based on the object-oriented programming concept of a class. A class is a software construct that is used for grouping a set of related variables together with the subroutines and functions that operate on them. We use classes in ESMF because they help to organize the code, and often make it easier to maintain and understand. A particular instance of a class is called an object. For example, Field is an ESMF class. An actual Field called temperature is an object. That is about as far as we will go into software engineering terminology.

The Fortran interface is implemented so that the variables associated with a class are stored in a derived type. For example, an ESMF_Field derived type stores the data array, grid information, and metadata associated with a physical field. The derived type for each class is stored in a Fortran module, and the operations associated with each class are defined as module procedures. We use the Fortran features of generic functions and optional arguments extensively to simplify our interfaces.

The modules for ESMF are bundled together and can be accessed with a single USE statement, USE ESMF.

6.1 Standard Methods and Interface Rules

ESMF defines a set of standard methods and interface rules that hold across the entire API. These are:


6.2 Deep and Shallow Classes

The ESMF contains two types of classes.

Deep classes require ESMF_<Class>Create() and ESMF_<Class>Destroy() calls. They involve memory allocation take significant time to set up (involving memory management) and should not be created in a time-critical portion of code. Deep objects persist even after the method in which they were created has returned. Most classes in ESMF, including GridComp, CplComp, State, Fields, FieldBundles, Arrays, ArrayBundles, Grids, and Clocks, fall into this category.

Shallow classes do not possess ESMF_<Class>Create() and ESMF_<Class>Destroy() calls. They are simply declared and their values set using an ESMF_<Class>Set() call. Examples of shallow classes are Time, TimeInterval, and ArraySpec. Shallow classes do not take long to set up and can be declared and set within a time-critical code segment. Shallow objects stop existing when the method in which they were declared has returned.

An exception to this is when a shallow object, such as a Time, is stored in a deep object such as a Clock. The Clock then carries a copy of the Time in persistent memory. The Time is deallocated with the ESMF_ClockDestroy() call.

See Section 10, Overall Design and Implementation Notes, for a brief discussion of deep and shallow classes from an implementation perspective. For an in-depth look at the design and inter-language issues related to deep and shallow classes, see the ESMF Implementation Report.

6.3 Special Methods

The following are special methods which, in one case, are required by any application using ESMF, and in the other case must be called by any application that is using ESMF Components.

6.4 The ESMF Data Hierarchy

The ESMF API is organized around an hierarchy of classes that contain model data. The operations that are performed on model data, such as regridding, redistribution, and halo updates, are methods of these classes.

The main data classes in ESMF, in order of increasing complexity, are:

Underlying these data classes are native language arrays. ESMF allows you to reference an existing Fortran array to an ESMF Array or Field so that ESMF data classes can be readily introduced into existing code. You can perform communication operations directly on Fortran arrays through the VM class, which serves as a unifying wrapper for distributed and shared memory communication libraries.


6.5 ESMF Spatial Classes

Like the hierarchy of model data classes, ranging from the simple to the complex, ESMF is organized around an hierarchy of classes that represent different spaces associated with a computation. Each of these spaces can be manipulated, in order to give the user control over how a computation is executed. For Earth system models, this hierarchy starts with the address space associated with the computer and extends to the physical region described by the application. The main spatial classes in ESMF, from those closest to the machine to those closest to the application, are:

6.6 ESMF Maps

In order to define how the index spaces of the spatial classes relate to each other, we require either implicit rules (in which case the relationship between spaces is defined by default), or special Map arrays that allow the user to specify the desired association. The form of the specification is usually that the position of the array element carries information about the first object, and the value of the array element carries information about the second object. ESMF includes a distGridToArrayMap, a gridToFieldMap, a distGridToGridMap, and others.

6.7 ESMF Specification Classes

It can be useful to make small packets of descriptive parameters. ESMF has one of these:

6.8 ESMF Utility Classes

There are a number of utilities in ESMF that can be used independently. These are:

7 Overall Rules and Behavior

7.1 Local and Global Views and Associated Conventions

ESMF data objects such as Fields are distributed over DEs, with each DE getting a portion of the data. Depending on the task, a local or global view of the object may be preferable. In a local view, data indices start with the first element on the DE and end with the last element on the same DE. In a global view, there is an assumed or specified order to the set of DEs over which the object is distributed. Data indices start with the first element on the first DE, and continue across all the elements in the sequence of DEs. The last data index represents the number of elements in the entire object. The DistGrid provides the mapping between local and global data indices.

The convention in ESMF is that entities with a global view have no prefix. Entities with a DE-local (and in some cases, PET-local) view have the prefix ``local.''

Just as data is distributed over DEs, DEs themselves can be distributed over PETs. This is an advanced feature for users who would like to create multiple local chunks of data, for algorithmic or performance reasons. Local DEs are those DEs that are located on the local PET. Local DE labeling always starts at 0 and goes to localDeCount-1, where localDeCount is the number of DEs on the local PET. Global DE numbers also start at 0 and go to deCount-1. The DELayout class provides the mapping between local and global DE numbers.

7.2 Allocation Rules

The basic rule of allocation and deallocation for the ESMF is: whoever allocates it is responsible for deallocating it.

ESMF methods that allocate their own space for data will deallocate that space when the object is destroyed. Methods which accept a user-allocated buffer, for example ESMF_FieldCreate() with the ESMF_DATACOPY_REFERENCE flag, will not deallocate that buffer at the time the object is destroyed. The user must deallocate the buffer when all use of it is complete.

Classes such as Fields, FieldBundles, and States may have Arrays, Fields, Grids and FieldBundles created externally and associated with them. These associated items are not destroyed along with the rest of the data object since it is possible for the items to be added to more than one data object at a time (e.g. the same Grid could be part of many Fields). It is the user's responsibility to delete these items when the last use of them is done.

7.3 Assignment, Equality, Copying and Comparing Objects

The equal sign assignment has not been overloaded in ESMF, thus resulting in the standard Fortran behavior. This behavior has been documented as the first entry in the API documentation section for each ESMF class. For deep ESMF objects the assignment results in setting an alias the the same ESMF object in memory. For shallow ESMF objects the assignment is essentially a equivalent to a copy of the object. For deep classes the equality operators have been overloaded to test for the alias condition as a counter part to the assignment behavior. This and the not equal operator are documented following the assignemnt in the class API documentation sections.

Deep object copies are implemented as a special variant of the ESMF_<Class>Create() methods. It takes an existing deep object as on of the required arguments. At this point not all deep classes have ESMF_<Class>Create() methods that allow object copy.

Due to the complexity of deep classes there are many aspects when comparing two objects of the same class. ESMF provide ESMF_<Class>Match() methods, which are functions that return a class specific match flag. At this point not all deep classes have ESMF_<Class>Match() methods that allow deep object comparison.

7.4 Attributes

Attributes are (name, value) pairs, where the name is a character string and the value can be either a single value or list of integer, real, double precision, logical, or character values. Attributes can be associated with Fields, FieldBundles, and States. Mixed types are not allowed in a single attribute, and all attribute names must be unique within a single object. Attributes are set by name, and can be retrieved either directly by name or by querying for a count of attributes and retrieving names and values by index number.

8 Integrating ESMF into Applications

Depending on the requirements of the application, the user may want to begin integrating ESMF in either a top-down or bottom-up manner. In the top-down approach, tools at the superstructure level are used to help reorganize and structure the interactions among large-scale components in the application. It is appropriate when interoperability is a primary concern; for example, when several different versions or implementations of components are going to be swapped in, or a particular component is going to be used in multiple contexts. Another reason for deciding on a top-down approach is that the application contains legacy code that for some reason (e.g., intertwined functions, very large, highly performance-tuned, resource limitations) there is little motivation to fully restructure. The superstructure can usually be incorporated into such applications in a way that is non-intrusive.

In the bottom-up approach, the user selects desired utilities (data communications, calendar management, performance profiling, logging and error handling, etc.) from the ESMF infrastructure and either writes new code using them, introduces them into existing code, or replaces the functionality in existing code with them. This makes sense when maximizing code reuse and minimizing maintenance costs is a goal. There may be a specific need for functionality or the component writer may be starting from scratch. The calendar management utility is a popular place to start.

8.1 Using the ESMF Superstructure

The following is a typical set of steps involved in adopting the ESMF superstructure. The first two tasks, which occur before an ESMF call is ever made, have the potential to be the most difficult and time-consuming. They are the work of splitting an application into components and ensuring that each component has well-defined stages of execution. ESMF aside, this sort of code structure helps to promote application clarity and maintainability, and the effort put into it is likely to be a good investment.

  1. Decide how to organize the application as discrete Gridded and Coupler Components. This might involve reorganizing code so that individual components are cleanly separated and their interactions consist of a minimal number of data exchanges.

  2. Divide the code for each component into initialize, run, and finalize methods. These methods can be multi-phase, e.g., init_1, init_2.

  3. Pack any data that will be transferred between components into ESMF Import and Export State data structures. This is done by first wrapping model data in either ESMF Arrays or Fields. Arrays are simpler to create and use than Fields, but carry less information and have a more limited range of operations. These Arrays and Fields are then added to Import and Export States. They may be packed into ArrayBundles or FieldBundles first, for more efficient communications. Metadata describing the model data can also be added. At the end of this step, the data to be transferred between components will be in a compact and largely self-describing form.

  4. Pack time information into ESMF time management data structures.

  5. Using code templates provided in the ESMF distribution, create ESMF Gridded and Coupler Components to represent each component in the user code.

  6. Write a set services routine that sets ESMF entry points for each user component's initialize, run, and finalize methods.

  7. Run the application using an ESMF Application Driver.

9 Master List of Constants

9.1 ESMF_ALARMLIST

This flag is documented in section 42.2.1.


9.2 ESMF_DIM_ARB

DESCRIPTION:
An integer named constant which is used to indicate that a particular dimension is arbitrarily distributed.

9.3 ESMF_ATTGETCOUNT

This flag is documented in section 36.6.1.


9.4 ESMF_ATTRECONCILE

DESCRIPTION:
Indicate whether or not to handle metadata (Attributes) in ESMF_StateReconcile().

The type of this flag is:

type(ESMF_AttReconcileFlag)

The valid values are:

ESMF_ATTRECONCILE_ON
Attribute reconciliation will be turned on.
ESMF_ATTRECONCILE_OFF
Attribute reconciliation will be turned off.

9.5 ESMF_ATTTREE

This flag is documented in section 36.6.2.

9.6 ESMF_ATTWRITE

This flag is documented in section 36.6.3.

9.7 ESMF_CALKIND

This flag is documented in section 38.2.1.


9.8 ESMF_COMPTYPE

DESCRIPTION:
Indicate the type of a Component.

The type of this flag is:

type(ESMF_CompType_Flag)

The valid values are:

ESMF_COMPTYPE_GRID
A ESMF_GridComp object.
ESMF_COMPTYPE_CPL
A ESMF_CplComp objects.


9.9 ESMF_CONTEXT

DESCRIPTION:
Indicates the type of VM context in which a Component will be executing its standard methods.

The type of this flag is:

type(ESMF_Context_Flag)

The valid values are:

ESMF_CONTEXT_OWN_VM
The component is running in its own, separate VM context. Resources are inherited from the parent but can be arranged to fit the component's requirements.
ESMF_CONTEXT_PARENT_VM
The component uses the parent's VM for resource management. Compared to components that use their own VM context components that run in the parent's VM context are more light-weight with respect to the overhead of calling into their initialize, run and finalize methods. Furthermore, VM-specific properties remain unchanged when going from the parent component to the child component. These properties include the MPI communicator, the number of PETs, the PET labeling, communication attributes, threading-level.

9.10 ESMF_COORDSYS

This flag is documented in section 28.2.1.


9.11 ESMF_COPY

DESCRIPTION:
Indicates which type of copy behavior is used when copying ESMF objects.

The type of this flag is:

type(ESMF_Copy_Flag)

The valid values are:

ESMF_COPY_ALIAS
The destination of the copy becomes an alias of the source object.
ESMF_COPY_REFERENCE
All local data of the object is coped by value, and pointer valued data is referenced.
ESMF_COPY_VALUE
All data and pointers are copied to the destination object, nothing is referenced.


9.12 ESMF_DATACOPY

DESCRIPTION:
Indicates whether to reference a data item or make a copy of it.

The type of this flag is:

type(ESMF_DataCopy_Flag)

The valid values are:

ESMF_DATACOPY_VALUE
Copy the data item to another buffer.
ESMF_DATACOPY_REFERENCE
Reference the data item.


9.13 ESMF_DECOMP

DESCRIPTION:
Indicates how DistGrid elements are decomposed over DEs.

The type of this flag is:

type(ESMF_Decomp_Flag)

The valid values are:

ESMF_DECOMP_BALANCED
Decompose elements as balanced as possible across DEs. The maximum difference in number of elements per DE is 1, with the extra elements on the lower DEs.
ESMF_DECOMP_CYCLIC
Decompose elements cyclically across DEs.
ESMF_DECOMP_DEFAULT
Use default decomposition behavior. Currently equal to ESMF_DECOMP_BALANCED.
ESMF_DECOMP_RESTFIRST
Divide elements over DEs. Assign the rest of this division to the first DE.
ESMF_DECOMP_RESTLAST
Divide elements over DEs. Assign the rest of this division to the last DE.

9.14 ESMF_DIRECTION

This flag is documented in section 41.2.1.

9.15 ESMF_DISTGRIDMATCH

This flag is documented in section 32.2.1.

9.16 ESMF_END

This flag is documented in section 14.2.1.

9.17 ESMF_FIELDSTATUS

This flag is documented in section 23.2.1.

9.18 ESMF_FILEFORMAT

This flag is documented in section [*].


9.19 ESMF_GEOMTYPE

DESCRIPTION:
Different types of geometries upon which an ESMF Field or ESMF Fieldbundle may be built.

The type of this flag is:

type(ESMF_GeomType_Flag)

The valid values are:

ESMF_GEOMTYPE_GRID
An ESMF_Grid, a structured grid composed of one or more logically rectangular tiles
ESMF_GEOMTYPE_MESH
An ESMF_Mesh, an unstructured grid
ESMF_GEOMTYPE_XGRID
An ESMF_XGrid, an exchange grid
ESMF_TYPEKIND_LOCSTREAM
An ESMF_LocStream, a disconnected series of points with associated key values

9.20 ESMF_GRIDCONN

This flag is documented in section 28.2.2.

9.21 ESMF_GRIDITEM

This flag is documented in section 28.2.3.

9.22 ESMF_GRIDMATCH

This flag is documented in section 28.2.4.

9.23 ESMF_GRIDSTATUS

This flag is documented in section 28.2.5.


9.24 ESMF_INDEX

DESCRIPTION:
Indicates whether index is local (per DE) or global (per object).

The type of this flag is:

type(ESMF_Index_Flag)

The valid values are:

ESMF_INDEX_DELOCAL
Indicates that DE-local index space starts at lower bound 1 for each DE.
ESMF_INDEX_GLOBAL
Indicates that global indices are used. This means that DE-local index space starts at the global lower bound for each DE.
ESMF_INDEX_USER
Indicates that the DE-local index bounds are explicitly set by the user.


9.25 ESMF_IOFMT

DESCRIPTION:
Indicates IO format options that are currently supported.

The type of this flag is:

type(ESMF_IOFmtFlag)

The valid values are:

ESMF_IOFMT_BIN
Binary format.
ESMF_IOFMT_NETCDF
NETCDF and PNETCDF format.


9.26 ESMF_KIND

DESCRIPTION:
Named constants to be used as kind-parameter in Fortran variable declarations. For example:

  integer(ESMF_KIND_I4)       :: integerVariable
  integer(kind=ESMF_KIND_I4)  :: integerVariable
  real(ESMF_KIND_R4)          :: realVariable
  real(kind=ESMF_KIND_R4)     :: realVariable
The Fortran standard does not mandate what numeric values correspond to actual number of bytes allocated for the various kinds. The following constants are defined by ESMF to be correct across the supported Fortran compilers. Note that not all compilers support every kind listed below; in particular 1 and 2 byte integers can be problematic.

The type of these named constants is:

integer

The named constants are:

ESMF_KIND_I1
Kind-parameter for 1 byte integer.
ESMF_KIND_I2
Kind-parameter for 2 byte integer.
ESMF_KIND_I4
Kind-parameter for 4 byte integer.
ESMF_KIND_I8
Kind-parameter for 8 byte integer.
ESMF_KIND_R4
Kind-parameter for 4 byte real.
ESMF_KIND_R8
Kind-parameter for 8 byte real.

9.27 ESMF_LOGERR

This flag is documented in section 44.2.1.

9.28 ESMF_LOGKIND

This flag is documented in section 44.2.2.

9.29 ESMF_LOGMSG

This flag is documented in section 44.2.3.

9.30 ESMF_MESHELEMTYPE

This flag is documented in section 30.2.1.


9.31 ESMF_METHOD

DESCRIPTION:
Specify standard ESMF Component method.

The type of this flag is:

type(ESMF_Method_Flag)

The valid values are:

ESMF_METHOD_FINALIZE
Finalize method.
ESMF_METHOD_INITIALIZE
Initialize method.
ESMF_METHOD_READRESTART
ReadRestart method.
ESMF_METHOD_RUN
Run method.
ESMF_METHOD_WRITERESTART
WriteRestart method.

9.32 ESMF_PIN

This flag is documented in section 45.2.1.

9.33 ESMF_POLEMETHOD

This flag is documented in section 23.2.2.

9.34 ESMF_POLEKIND

This flag is documented in section 28.2.6.


9.35 ESMF_REDUCE

DESCRIPTION:
Indicates reduce operation

The type of this flag is:

type(ESMF_Reduce_Flag)

The valid values are:

ESMF_REDUCE_SUM
Use arithmetic sum to add all data elements.
ESMF_REDUCE_MIN
Determine the minimum of all data elements.
ESMF_REDUCE_MAX
Determine the maximum of all data elements.


9.36 ESMF_REGION

DESCRIPTION:
Specifies various regions in the data layout of an Array or Field object.

The type of this flag is:

type(ESMF_Region_Flag)

The valid values are:

ESMF_REGION_TOTAL
Total allocated memory.
ESMF_REGION_SELECT
Region of operation-specific elements.
ESMF_REGION_EMPTY
The empty region contains no elements.

9.37 ESMF_REGRIDMETHOD

This flag is documented in section 23.2.3.


9.38 ESMF_ROUTESYNC

DESCRIPTION:
Switch between blocking and non-blocking execution of RouteHandle based communication calls. Every RouteHandle based communication method contains an optional argument routesyncflag that is of type ESMF_RouteSync_Flag.

The type of this flag is:

type(ESMF_RouteSync_Flag)

The valid values are:

ESMF_ROUTESYNC_BLOCKING
Execute a precomputed communication pattern in blocking mode. This mode guarantees that when the method returns all PET-local data transfers, both in-bound and out-bound, have finished.
ESMF_ROUTESYNC_NBSTART
Start executing a precomputed communication pattern in non-blocking mode. When a method returns from being called in this mode, it guarantees that all PET-local out-bound data has been transferred. It is now safe for the user to overwrite out-bound data elements. No guarantees are made for in-bound data elements at this stage. It is unsafe to access these elements until a call in ESMF_ROUTESYNC_NBTESTFINISH mode has been issued and has returned with finishedflag equal to .true., or a call in ESMF_ROUTESYNC_NBWAITFINISH mode has been issued and has returned.
ESMF_ROUTESYNC_NBTESTFINISH
Test whether the transfer of data of a precomputed communication pattern, started with ESMF_ROUTESYNC_NBSTART, has completed. Finish up as much as possible and set the finishedflag to .true. if all data operations have completed, or .false. if there are still outstanding transfers. Only after a finishedflag equal to .true. has been returned is it safe to access any of the in-bound data elements.
ESMF_ROUTESYNC_NBWAITFINISH
Wait (i.e. block) until the transfer of data of a precomputed communication pattern, started with ESMF_ROUTESYNC_NBSTART, has completed. Finish up all data operations and set the returned finishedflag to .true.. It is safe to access any of the in-bound data elements once the call has returned.
ESMF_ROUTESYNC_CANCEL
Cancel outstanding transfers for a precomputed communication pattern.

9.39 ESMF_SERVICEREPLY

This flag is documented in section 45.2.2.

9.40 ESMF_STAGGERLOC

This flag is documented in section 28.2.7.


9.41 ESMF_STARTREGION

DESCRIPTION:
Specifies the start of the effective halo region of an Array or Field object.

The type of this flag is:

type(ESMF_StartRegion_Flag)

The valid values are:

ESMF_STARTREGION_EXCLUSIVE
Region of elements that are exclusively owned by the local DE.
ESMF_STARTREGION_COMPUTATIONAL
User defined region, greater or equal to the exclusive region.

9.42 ESMF_STATEINTENT

This flag is documented in section 18.2.1.

9.43 ESMF_STATEITEM

This flag is documented in section 18.2.2.


9.44 ESMF_SYNC

DESCRIPTION:
Indicates method blocking behavior and PET synchronization for VM communication methods, as well as for standard Component methods, such as Initialize(), Run() and Finalize().

For VM communication calls the ESMF_SYNC_BLOCKING and ESMF_SYNC_NONBLOCKING modes provide behavior that is practically identical to the blocking and non-blocking communication calls familiar from MPI.

The details of how the blocking mode setting affects Component methods are more complex. This is a consequence of the fact that ESMF Components can be executed in threaded or non-threaded mode. However, in the default, non-threaded case, where an ESMF application runs as a pure MPI or mpiuni program, most of the complexity is removed.

See the VM item in 6.5 for an explanation of the PET and VAS concepts used in the following descriptions.

The type of this flag is:

type(ESMF_Sync_Flag)

The valid values are:

ESMF_SYNC_BLOCKING
Communication calls: The called method will block until all (PET-)local operations are complete. After the return of a blocking communication method it is safe to modify or use all participating local data.

Component calls: The called method will block until all PETs of the VM have completed the operation.

For a non-threaded, pure MPI component the behavior is identical to calling a barrier before returning from the method. Generally this kind of rigid synchronization is not the desirable mode of operation for an MPI application, but may be useful for application debugging. In the opposite case, where all PETs of the component are running as threads in shared memory, i.e. in a single VAS, strict synchronization of all PETs is required to prevent race conditions.

ESMF_SYNC_VASBLOCKING
Communication calls: Not available for communication calls.

Component calls: The called method will block each PET until all operations in the PET-local VAS have completed.

This mode is a combination of ESMF_SYNC_BLOCKING and ESMF_SYNC_NONBLOCKING modes. It provides a default setting that leads to the typically desirable behavior for pure MPI components as well as those that share address spaces between PETs.

For a non-threaded, pure MPI component each PET returns independent of the other PETs. This is generally the expected behavior in the pure MPI case where calling into a component method is practically identical to a subroutine call without extra synchronization between the processes.

In the case where some PETs of the component are running as threads in shared memory ESMF_SYNC_VASBLOCKING becomes identical to ESMF_SYNC_BLOCKING within thread groups, to prevent race conditions, while there is no synchronization between the thread groups.

ESMF_SYNC_NONBLOCKING
Communication calls: The called method will not block but returns immediately after initiating the requested operation. It is unsafe to modify or use participating local data before all local operations have completed. Use the ESMF_VMCommWait() or ESMF_VMCommQueueWait() method to block the local PET until local data access is safe again.

Component calls: The behavior of this mode is fundamentally different for threaded and non-threaded components, independent on whether the components use shared memory or not. The ESMF_SYNC_NONBLOCKING mode is the most complex mode for calling component methods and should only be used if the extra control, described below, is absolutely necessary.

For non-threaded components (the ESMF default) calling a component method with ESMF_SYNC_NONBLOCKING is identical to calling it with ESMF_SYNC_VASBLOCKING. However, different than for ESMF_SYNC_VASBLOCKING, a call to ESMF_GridCompWait() or ESMF_CplCompWait() is required in order to deallocate memory internally allocated for the ESMF_SYNC_NONBLOCKING mode.

For threaded components the calling PETs of the parent component will not be blocked and return immediately after initiating the requested child component method. In this scenario parent and child components will run concurrently in identical VASs. This is the most complex mode of operation. It is unsafe to modify or use VAS local data that may be accessed by concurrently running components until the child component method has completed. Use the appropriate ESMF_GridCompWait() or ESMF_CplCompWait() method to block the local parent PET until the child component method has completed in the local VAS.


9.45 ESMF_TYPEKIND

DESCRIPTION:
Named constants used to indicate type and kind combinations supported by the overloaded ESMF interfaces. The corresponding Fortran kind-parameter constants are described in section 9.26.

The type of these named constants is:

type(ESMF_TypeKind_Flag)

The named constants are:

ESMF_TYPEKIND_I1
Indicates 1 byte integer.
ESMF_TYPEKIND_I2
Indicates 2 byte integer.
ESMF_TYPEKIND_I4
Indicates 4 byte integer.
ESMF_TYPEKIND_I8
Indicates 8 byte integer.
ESMF_TYPEKIND_R4
Indicates 4 byte real.
ESMF_TYPEKIND_R8
Indicates 8 byte real.


9.46 ESMF_UNMAPPEDACTION

DESCRIPTION:
Indicates what action to take with respect to unmapped destination points and the entries of the sparse matrix that correspond to these points.

The type of this flag is:

type(ESMF_UnmappedAction_Flag)

The valid values are:

ESMF_UNMAPPEDACTION_ERROR
An error is issued when there exist destination points in a regridding operation that are not mapped by corresponding source points.
ESMF_UNMAPPEDACTION_IGNORE
Destination points which do not have corresponding source points are ignored and zeros are used for the entries of the sparse matrix that is generated.


9.47 ESMF_VERSION

DESCRIPTION:
The following named constants define the precise version of ESMF in use.

ESMF_VERSION_BETASNAPSHOT
Constant of type logical indicating beta snapshot phase (.true. for any version during the pre-release development phase, .false. for any released version of the software).
ESMF_VERSION_MAJOR
Constant of type integer indicating the major version number (e.g. 5 for v5.2.0r).
ESMF_VERSION_MINOR
Constant of type integer indicating the minor version number (e.g. 2 for v5.2.0r).
ESMF_VERSION_PATCHLEVEL
Constant of type integer indicating the patch level of a specific revision (e.g. 0 for v5.2.0r, or 1 for v5.2.0rp1).
ESMF_VERSION_PUBLIC
Constant of type logical indicating public vs. internal release status (e.g. .true. for v5.2.0r, or .false. for v5.2.0).
ESMF_VERSION_REVISION
Constant of type integer indicating the revision number (e.g. 0 for v5.2.0r).
ESMF_VERSION_STRING
Constant of type character holding the exact release version string (e.g. "5.2.0r").

9.48 ESMF_XGRIDSIDE

This flag is documented in section 31.2.1.


10 Overall Design and Implementation Notes

  1. Deep and shallow classes. The deep and shallow classes described in Section 6.2 differ in how and where they are allocated within a multi-language implementation environment. We distinguish between the implementation language, which is the language a method is written in, and the calling language, which is the language that the user application is written in. Deep classes are allocated off the process heap by the implementation language. Shallow classes are allocated off the stack by the calling language.

  2. Base class. All ESMF classes are built upon a Base class, which holds a small set of system-wide capabilities.


next up previous contents
Next: 2 Applications Up: ESMF_refdoc Previous: Contents   Contents
esmf_support@list.woc.noaa.gov