% $Id$

%\subsection{Use and Examples}

A Field serves as an annotator of data, since it carries 
a description of the grid it is associated with and metadata 
such as name and units.  Fields can be used in this capacity
alone, as convenient, descriptive containers into which arrays 
can be placed and retrieved.  However, for most codes the primary 
use of Fields is in the context of import and export States,
which are the objects that carry coupling information between 
Components.  Fields enable data to be self-describing, and a
State holding ESMF Fields contains data in a standard format
that can be queried and manipulated.  

The sections below go into more detail about Field usage.

\subsubsection{Field create and destroy}

Fields can be created and destroyed at any time during 
application execution.  However, these Field methods require 
some time to complete.  We do not recommend that the user
create or destroy Fields inside performance-critical 
computational loops.

All versions of the {\tt ESMF\_FieldCreate()} 
routines require a Grid object as input, or require a Grid
be added before most operations involving Fields can be performed.
The Grid contains the information needed to know which 
Decomposition Elements (DEs) are participating in 
the processing of this Field, and which subsets of the data
are local to a particular DE.

The details of how the create process happens depend
on which of the variants of the {\tt ESMF\_FieldCreate()} 
call is used.  Some of the variants are discussed below.

There are versions of the {\tt ESMF\_FieldCreate()} interface
which create the Field based on the input Grid.  The ESMF
can allocate the proper amount of 
space but not assign initial values.  The user code
can then get the pointer to the uninitialized buffer and 
set the initial data values.

Other versions of the {\tt ESMF\_FieldCreate()} interface
allow user code to attach arrays that have already been
allocated by the user.  Empty Fields can also be created in
which case the data can be added at some later time.

For versions of Create which do not specify data values,
user code can create an ArraySpec object, which
contains information about the typekind and rank of the
data values in the array.  Then at Field create time, the
appropriate amount of memory is allocated to contain the
data which is local to each DE.

When finished with a {\tt ESMF\_Field}, the {\tt ESMF\_FieldDestroy} method
removes it.  However, the objects inside the {\tt ESMF\_Field}
created externally should be destroyed separately, 
since objects can be added to
more than one {\tt ESMF\_Field}.  For example, the same {\tt ESMF\_Grid}
can be referenced by multiple {\tt ESMF\_Field}s.  In this case the
internal Grid is not deleted by the {\tt ESMF\_FieldDestroy} call.
