Switch to the new "transferAllWithNamespace" option for the

FieldTransferPolicy attribute. Update documentation.

src/addon/NUOPC/doc/NUOPC_FieldMirror.tex

@@ -3,12 +3,14 @@
 
 \label{FieldMirror}
 
-In some cases it is helpful for a NUOPC component to automatically mirror or match the set of fields advertised by another component.  One purpose of this is to automatically resolve the import data dependencies of a component, by setting up a component that exactly provides all of the needed fields.  This is currently used in the NUOPC Component Explorer:  when driving a child NUOPC Model with required import fields, the Component Explorer uses the field mirroring capability to advertise in the driver-self export State the exact set of fields advertised in the child NUOPC Model.  This ensures that the entire Initialize Phase Sequence will complete (because all dependencies are satisfied) and all phases can be exercised by the Component Explorer.
+In some cases it is useful for a NUOPC component to match the set of fields advertised by another component, e.g. in order to connect to every field. NUOPC provides the concept of {\em field mirroring} that allows automatic matching by "mirroring" the fields of another component in their import- or exportState into their own States. One purpose of this is to automatically resolve the import data dependencies of a component, by setting up a component that exactly provides all of the needed fields.
 
 The field mirror capability is also useful with NUOPC Mediators since these components often exactly reflect, in separate States, the sets of fields of each of the connected components.  The field mirroring capability, therefore, can be used to ensure that a Mediator is always capable of accepting fields from connected components, and removes the need to specify field lists in multiple places, i.e., both within a set of Model components connected to a Mediator and within the Mediator itself.
 
-To access the field mirror capability, a component sets the {\tt FieldTransferPolicy} attribute during {\tt label\_Advertise}. The attribute is set on the Import- and/or Export- States to trigger field mirroring for each state, respectively.  The default value of "TransferNone" indicates that no fields should be mirrored.  The other options, "TransferAll", indicates that fields should be mirrored in the State of a connected component and "TransferAllAsNests", also indicates that fields should be mirrored in the State of a connected component but in this case, fields are added to nested state for each provider component.
+To access the field mirror capability, a component sets the {\tt FieldTransferPolicy} attribute during {\tt label\_Advertise}. The attribute is set on the Import- and/or Export- States to trigger field mirroring for each state, respectively.  The default value of "TransferNone" indicates that no fields should be mirrored.  The other available options are "TransferAll" and "transferAllWithNamespace". Both options mirror transfer all of the fields from all of the connected States into the State that carries the attribute. The "TransferAll" option results in flat structure with all of the mirrored fields added directly to the acceptor State. A flat structure like this is typically the preferred situation for an ExportState, where the same fields might be connected to multiple consumer components. The "transferAllWithNamespace" option also mirrors all of the field from the connected State, but creates separate Namespaces for each connection, placing the associated mirrored fields into the respective nested State. A nested structure like this useful for an ImportState where connections are being made with multiple producer components. In this case the consumer component can query the "Namespace" attribute of each nested State to infer the component label of the associated producer components.
 
-Each Connector consider the {\tt FieldTransferPolicy} Attribute on both its import and export States.  If {\em both} States have a {\tt FieldTransferPolicy} of "TransferAll" or "TransferAllAsNests", then fields are transferred between the States in both directions (i.e., import to export and export to import).  In case of "TransferAllAsNests", the received State by acceptor will have nested states for each provider. The transfer process works as follows:  First, the {\tt TransferOfferGoemObject} attribute is reversed between the providing side and accepting side.  Intuitively, if a field from the providing component is to be mirrored and it can provide its own geometric object, then the mirrored field on the accepting side should be set to accept a geometric object.  Then, the field to be mirrored is advertised in the accepting State using a call to {\tt NUOPC\_Advertise()} such that the mirrored field shares the same Standard Name. The accepting State will have nested states if {\tt FieldTransferPolicy} is set to "TransferAllAsNests".
+Each Connector considers the {\tt FieldTransferPolicy} attribute on both its import and export States.  Each State that has the {\tt FieldTransferPolicy} attribute set to "transferAll" or "transferAllWithNamespace", will have then fields of the respecive other State mirror transferred. If {\em both} States have the {\tt FieldTransferPolicy} attribute set to trigger the mirror transfer, then fields are mirrored in both directions (i.e. import to export and export to import).
 
-Components have the opportunity, using specialiozation point {\tt label\_ModifyAdvertised}, to modify any of the mirrored Fields in their Import/ExportState. After this the initialization sequence continues as usual.  Since fields to be mirrored have been advertised with matching Standard Names, the field pairing algorithm will now match them in the usual way thereby establishing a connection between the original and mirrored fields.
+The transfer process works as follows:  First, the {\tt TransferOfferGoemObject} attribute is reversed between the providing side and accepting side. This is because if a field from the providing component is to be mirrored and it {\em can} provide its own geometric object, then the mirrored field on the accepting side should be set to {\em accept} a geometric object.  The mirrored field is advertised in the accepting State using a call to {\tt NUOPC\_Advertise()} such that the mirrored field shares the same StandardName.
+
+Components have the opportunity to modify or remove any of the mirrored Fields in their Import/ExportState by using the {\tt label\_ModifyAdvertised} specialization point. After this point the initialization sequence continues as usual. Since the mirrored fields have been advertised with matching StandardName attribute, the field pairing algorithm now matches them in the usual manner, thereby establishing a connection between the original and the mirrored fields.

src/addon/NUOPC/doc/NUOPC_Field_metadata.tex

@@ -3,7 +3,7 @@
 using the JSON Pointer "/NUOPC/Instance/" prefix followed by the "Attribute name"
 as per the table below. E.g. "StandardName" is accessed using {\tt key="/NUOPC/Instance/StandardName"}.
 
-\begin{longtable}{|p{.22\textwidth}|p{.6\textwidth}|p{.2\textwidth}|}
+\begin{longtable}{|p{.3\textwidth}|p{.4\textwidth}|p{.3\textwidth}|}
      \hline\hline
      {\bf Attribute name} & {\bf Definition} & {\bf Controlled vocabulary}\\
      \hline\hline
@@ -31,6 +31,5 @@
      {\tt MaxIndex} & Integer value list. If present equals the {\tt maxIndex} (of tile 1) of the provider field.during a GeomObject transfer. & {\em no restriction}\\ \hline
      {\tt TypeKind} & Integer value. If present equals the integer representation of {\tt typekind} of the provider field.during a GeomObject transfer. & {\em implementation dependent range}\\ \hline
      {\tt GeomLoc} & Integer value. If present equals the integer representation of {\tt staggerloc} (for Grid) or {\tt meshloc} (for Mesh) of the provider field.during a GeomObject transfer. & {\em implementation dependent range}\\ \hline
-     {\tt ProviderCompName} & String value holding the name of provider component that is indicated in run sequence\\ \hline
      \hline
 \end{longtable}

src/addon/NUOPC/doc/NUOPC_State_metadata.tex

@@ -3,12 +3,11 @@
 using the JSON Pointer "/NUOPC/Instance/" prefix followed by the "Attribute name"
 as per the table below. E.g. "Namespace" is accessed using {\tt key="/NUOPC/Instance/Namespace"}.
 
-\begin{longtable}{|p{.22\textwidth}|p{.6\textwidth}|p{.2\textwidth}|}
+\begin{longtable}{|p{.3\textwidth}|p{.4\textwidth}|p{.3\textwidth}|}
      \hline\hline
      {\bf Attribute name} & {\bf Definition} & {\bf Controlled vocabulary}\\
      \hline\hline
      {\tt Namespace}            & String value holding the namespace of all the objects contained in the State.& {\em no restriction}\\ \hline
-     {\tt FieldTransferPolicy}  & String value indicating to Connector to transfer/mirror Fields. & transferNone,\newline transferAll\\ \hline
-     {\tt CompName}             & String value holding the name of provider component that is indicated in run sequence\\ \hline
+     {\tt FieldTransferPolicy}  & String value indicating to Connector to transfer/mirror Fields. & transferNone,\newline transferAll,\newline transferAllWithNamespace\\ \hline
      \hline
 \end{longtable}

src/addon/NUOPC/src/NUOPC_Connector.F90

@@ -608,7 +608,7 @@ subroutine InitializeIPDv05p1(connector, importState, exportState, clock, rc)
       call doMirror(importState, exportState, acceptorVM=vm, rc=rc)
       if (ESMF_LogFoundError(rcToCheck=rc, msg=ESMF_LOGERR_PASSTHRU, &
         line=__LINE__, file=trim(name)//":"//FILENAME)) return  ! bail out
-    elseif (trim(exportXferPolicy)=="transferAllAsNests") then
+    elseif (trim(exportXferPolicy)=="transferAllWithNamespace") then
       ! access importState namespace so it can be transferred to exportState
       call NUOPC_GetAttribute(importState, name="Namespace", &
         value=namespace, rc=rc)
@@ -703,7 +703,7 @@ subroutine InitializeIPDv05p1(connector, importState, exportState, clock, rc)
       call doMirror(exportState, importState, acceptorVM=vm, rc=rc)
       if (ESMF_LogFoundError(rcToCheck=rc, msg=ESMF_LOGERR_PASSTHRU, &
         line=__LINE__, file=trim(name)//":"//FILENAME)) return  ! bail out
-    elseif (trim(importXferPolicy)=="transferAllAsNests") then
+    elseif (trim(importXferPolicy)=="transferAllWithNamespace") then
       ! access exportState namespace so it can be transferred to importState
       call NUOPC_GetAttribute(exportState, name="Namespace", &
         value=namespace, rc=rc)