% $Id$
%
% Earth System Modeling Framework
% Copyright (c) 2002-2023, 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.

%\subsection{Description}

Every ESMF application needs a driver code. Typically the driver layer is
implemented as the "main" of the application, although this is not strictly an
ESMF requirement. For most ESMF applications the task of the application driver
will be very generic: Initialize ESMF, create a top-level Component and call its
Initialize, Run and Finalize methods, before destroying the top-level Component
again and calling ESMF Finalize.

\begin{sloppypar}
ESMF provides a number of different application driver templates in the
{\tt \$ESMF\_DIR/src/Superstructure/AppDriver} directory. An appropriate one 
can be chosen depending on how the application is to be structured:
\end{sloppypar}

\begin{description}

\item[Sequential vs. Concurrent Execution]

In a sequential execution model, every Component executes
on all PETs, with each Component completing execution before
the next Component begins.  This has the appeal of 
simplicity of data consumption and production: when a Gridded 
Component starts, all required data is available for use, and when
a Gridded Component finishes, all data produced is ready for consumption
by the next Gridded Component.  This approach also has
the possibility of less data movement if the grid and
data decomposition is done such that each processor's memory contains
the data needed by the next Component.

In a concurrent execution model, subgroups of PETs run
Gridded Components and multiple Gridded Components are active at the 
same time.  Data exchange must be coordinated between Gridded 
Components so that data deadlock does not occur.  This strategy 
has the advantage of allowing coupling to other Gridded Components 
at any time during the computational process, including not 
having to return to the calling level of code before making 
data available.  

\item[Pairwise vs. Hub and Spoke]

Coupler Components are responsible for taking data from one
Gridded Component and putting it into the form expected by another 
Gridded Component.  This might include regridding, change of units, 
averaging, or binning.

Coupler Components can be written for {\it pairwise} data exchange: 
the Coupler Component takes data from a single Component and transforms 
it for use by another single Gridded Component.  This simplifies the 
structure of the Coupler Component code.

Couplers can also be written using a {\it hub and spoke} model where a
single Coupler accepts data from all other Components, can do data
merging or splitting, and formats data for all other Components.

Multiple Couplers, using either of the above two models or some mixture of
these approaches, are also possible.

\item[Implementation Language]

The ESMF framework currently has Fortran interfaces for all public functions. 
Some functions also have C interfaces, and the number of these is expected to 
increase over time. 


\item[Number of Executables]

The simplest way to run an application
is to run the same executable program on all PETs.  Different Components
can still be run on mutually exclusive PETs by using branching
(e.g., if this is PET 1, 2, or 3, run Component A, if it is
PET 4, 5, or 6 run Component B).  This is a {\bf SPMD} model, 
Single Program Multiple Data.  

The alternative is to start a different executable program on different
PETs.  This is a {\bf MPMD} model, Multiple Program Multiple Data.
There are complications with many job control systems on multiprocessor
machines in getting the different executables started, and getting
inter-process communications established.  ESMF currently has some
support for MPMD: different Components can run as separate executables,
but the Coupler that transfers data between the Components must still
run on the union of their PETs. This means that the Coupler Component
must be linked into all of the executables.

\end{description}



