% $Id$
%

\label{TransferGeom}

There are modeling scenarios where the need arises to transfer physical grid information from one component to another. One common situation is that of modeling systems that utilize Mediator components to implement the interactions between Model components. In these cases the Mediator often carries out computations on a Model's native grid and performs regridding to the grid of other Model components. It is both cumbersome and error prone to recreate the Model grid in the Mediator. To solve this problem, NUOPC implements a transfer protocol for {\tt ESMF\_Grid}, {\tt ESMF\_Mesh}, and {\tt ESMF\_LocStream} objects (generally referred to as GeomObjects) between Model and/or Mediator components during initialization.

The NUOPC Layer transfer protocol for GeomObjects is based on two Field attributes: {\tt TransferOfferGeomObject} and {\tt TransferActionGeomObject}. The {\tt TransferOfferGeomObject} attribute is used by the Model and/or Mediator components to indicate for each Field their intent for the associated GeomObject. The predefined values of this attribute are: "will provide", "can provide", and "cannot provide". The {\tt TransferOfferGeomObject} attribute must be set during {\tt label\_Advertise}.

The generic Connector uses the intents from both sides and constructs a response according to the table below. The Connector's response is available during {\tt label\_RealizeProvided}. It sets the value of the {\tt TransferActionGeomObject} attribute to either "provide" or "accept" on each Field. Fields indicating {\tt TransferActionGeomObject} equal to "provide" must be realized on a Grid, Mesh, or LocStream object in the Model/Mediator before returning from {\tt label\_RealizeProvided}.

Fields that hold "accept" for the value of the {\tt TransferActionGeomObject} attribute require two additional negotiation steps. During {\tt label\_AcceptTransfer} the Model/Mediator component can access the transferred Grid/Mesh/LocStream on the Fields that have the "accept" value. However, only the DistGrid, i.e. the decomposition and distribution information of the Grid/Mesh/LocStream is available at this stage, not the full physical grid information such as the coordinates. At this stage the Model/Mediator may modify this information by replacing the DistGrid object in the Grid/Mesh/LocStream. The DistGrid that is set on the Grid/Mesh/LocStream objects when leaving the Model/Mediator phase {\tt label\_AcceptTransfer} will consequently be used by the generic Connector to fully transfer the Grid/Mesh/LocStream object. The fully transferred objects are available on the Fields with "accept" during Model/Mediator phase {\tt label\_RealizeAccepted}, where they are used to realize the respective Field objects. At this point all Field objects are fully realized and the initialization process can proceed as usual.

The following table shows how the generic Connector sets the {\tt TransferActionGeomObject} attribute on the Fields according to the incoming value of {\tt TransferOfferGeomObject}.

\begin{tabular}[h]{|p{4.5cm}|p{4.5cm}|p{7cm}|}
     \hline\hline
     {\bf {\tt TransferOfferGeomObject} Incoming side A} & {\bf {\tt TransferOfferGeomObject} Incoming side B} & {\bf Outgoing setting by generic Connector}\\
     \hline\hline
     "will provide" & "will provide"    & A:{\tt TransferActionGeomObject}="provide" B:{\tt TransferActionGeomObject}="provide"\\ \hline
     "will provide" & "can provide"     & A:{\tt TransferActionGeomObject}="provide" B:{\tt TransferActionGeomObject}="accept"\\ \hline
     "will provide" & "cannot provide"  & A:{\tt TransferActionGeomObject}="provide" B:{\tt TransferActionGeomObject}="accept"\\ \hline
     "can provide"  & "will provide"    & A:{\tt TransferActionGeomObject}="accept"  B:{\tt TransferActionGeomObject}="provide"\\ \hline
     "can provide"  & "can provide"     & if (A is import side) then\newline
     A:{\tt TransferActionGeomObject}="provide" B:{\tt TransferActionGeomObject}="accept"
     if (B is import side) then\newline
     A:{\tt TransferActionGeomObject}="accept" B:{\tt TransferActionGeomObject}="provide"\\ \hline
     "can provide"  & "cannot provide"  & A:{\tt TransferActionGeomObject}="provide" B:{\tt TransferActionGeomObject}="accept"\\ \hline
     "cannot provide" & "will provide"  & A:{\tt TransferActionGeomObject}="accept"  B:{\tt TransferActionGeomObject}="provide"\\ \hline
     "cannot provide" & "can provide"   & A:{\tt TransferActionGeomObject}="accept"  B:{\tt TransferActionGeomObject}="provide"\\ \hline
     "cannot provide" & "cannot provide"& Flagged as error!\\ \hline
     \hline
\end{tabular}\newline
