.. _transfers-inter:

**************************
Inter-procedural Transfers
**************************

The inter-procedural transfers used by Adagio and Presto can transfer data from one or all blocks of the preceding or sending procedure to the subsequent or receiving procedure. The commands to control the transfers should appear at the procedure scope in the receiving procedure.

When using inter-procedural transfers, irrespective of the transfer type chosen, all global variables are copied by default from the sending procedure to the receiving procedure, and all appropriate element data is transferred from the sending to the receiving elements. Nodal data is transferred based on the type of analysis done in the two procedures. For example, if the first procedure is a quasistatic analysis and the second is an explicit transient dynamics analysis, the displacements of the nodes will be transferred but not their velocities.

.. warning::

   Transfer of data for node-based tetrahedra is currently not fully supported. A coupled analysis with node-based tetrahedra will only be correct if the tetrahedral elements are not deformed in the first (sending) procedure, in which case initialization in the second (receiving) procedure is appropriate.

The available commands are given below.

.. code-block:: sierrainput

   BEGIN PROCEDURAL TRANSFER [<string>name]
   
     BLOCK = <string list>block_name
     ASSEMBLY = <string list>assembly_name
     INCLUDE ALL BLOCKS
     REMOVE BLOCK = <string list>block_name
   
     ADDITIONAL ELEMENT VARIABLES = <string list>addElemVar
     ELEMENT VARIABLES = <string list>elemVar
     ELEMENT LIE VARIABLES = <string list>elemLieVar
     NODE VARIABLES =  <string list>nodeVar
     GLOBAL VARIABLES = <string list>globalVar
   
     ABSOLUTE SEARCH TOLERANCE = <real>tolerance (1.0e-5)
     SEARCH BOUNDING BOX INFLATION FACTOR = <real>scale_factor(0.1)
   
     BEGIN INTERPOLATION TRANSFER [<string>name]
   
       BLOCK BY BLOCK
       NEAREST ELEMENT COPY
   
       SEND BLOCKS = <string list>block_name
       SEND ASSEMBLIES = <string list>assembly_name
       SEND COORDINATES = ORIGINAL|CURRENT(ORIGINAL)
   
       RECEIVE BLOCKS = <string list>block_name
       RECEIVE ASSEMBLIES = <string list>assembly_name
       RECEIVE COORDINATES = ORIGINAL
   
       TRANSFORMATION TYPE = NONE|RIGIDBODY|REFLECT|WEDGE23D
   
       # ADDITIONAL REFLECT TRANSFER SPECIFICATION
       REFLECT PLANE = XY|YZ|ZX
   
       # ADDITIONAL WEDGE23D TRANSFER SPECIFICATION
       W23D ANGLE = <real>wedgeAngle
       W23D PLANE = XY|XZ|YX|YZ|ZX|ZY
       W23D REVOLVE ANGLE = <real>Angle
   
       NODAL TRANSFER TYPE = INTERPOLATE|GLOBAL_INTERPOLATION
                             (GLOBAL_INTERPOLATION)
   
     END [INTERPOLATION TRANSFER <string>name]
   
     BEGIN L2_PROJECTION TRANSFER [<string>name]
   
       BLOCK BY BLOCK
   
       SEND BLOCKS = <string list>block_name
       SEND ASSEMBLIES = <string list>assembly_name
       SEND COORDINATES = ORIGINAL|CURRENT(ORIGINAL)
   
       RECEIVE BLOCKS = <string list>block_name
       RECEIVE ASSEMBLIES = <string list>assembly_name
       RECEIVE COORDINATES = ORIGINAL
   
       TRANSFORMATION TYPE = ELEMENT2NODES|ELEMENT2ELEMENT
   
       LINEAR SOLVER = <string>solver_name(DEFAULT_FETI_SOLVER)
   
       PROJECTION TYPE = CONSISTENT|ROW_SUM_LUMPED|
          PROPORTIONAL_LUMPED(CONSISTENT)
   
       NODAL TRANSFER TYPE = INTERPOLATE|GLOBAL_INTERPOLATION
                             (INTERPOLATE)
   
     END [L2_PROJECTION TRANSFER <string>name]
   END [PROCEDURAL TRANSFER <string>name]

If the *same* finite element model is used in the sending and receiving regions, data may be *copied* directly from the sending to the receiving region. In this case, use of the ``BLOCK``, ``INCLUDE ALL BLOCKS``, ``ASSEMBLY``, and ``REMOVE BLOCK`` command lines alone will suffice to copy data for all blocks except those that are rigid bodies. Assemblies may contain blocks, or assemblies of these.

If *different* finite element models are used in the sending and receiving regions, or it is desired to transfer data for rigid bodies, an ``INTERPOLATION TRANSFER`` or ``L2_PROJECTION TRANSFER`` block must be used, and the ``BLOCK``, ``INCLUDE ALL BLOCKS``, ``ASSEMBLY``, and ``REMOVE BLOCK`` command lines in the ``PROCEDURAL TRANSFER`` block should *not* be used. If these commands, appropriate only for the direct *copy* of data, are used when not applicable, their behavior is undefined.

Copying Data with Inter-procedural Transfers
============================================

To copy data from one or more blocks in a sending region to the matching
blocks in the receiving region, use these line commands:

.. code-block:: sierrainput

   BLOCK = <string list>block_name
   ASSEMBLY = <string list>assembly_name
   INCLUDE ALL BLOCKS
   REMOVE BLOCK = <string list>block_name

The first of these, the ``BLOCK`` line command, is used to list blocks that should be copied. The ``ASSEMBLY`` line commands specifies assemblies of blocks should be copied. If it is desired to copy data for all blocks, use the ``INCLUDE ALL BLOCKS`` line command. Finally, one or more blocks may be removed from the set of all blocks with the ``REMOVE BLOCK`` line command. Either the ``BLOCK`` or ``INCLUDE ALL BLOCKS`` line command must appear for copy transfers. Assemblies may contain blocks, or assemblies of these.

Selecting Variables for Transfer
================================

By default, the code determines the variables to transfer: all global variables, and the sets of node and element variables necessary to initialize a new procedure where the previous procedure finished. Additional variables may be added to the default set with the ``ADDITIONAL ELEMENT VARIABLES`` command. The ``ADDITIONAL ELEMENT VARIABLES`` option is valid only when an :math:`L_2` projection  transfer is specified.

Alternatively, a manual subgroup of variables may be transferred with a combination of the ``ELEMENT VARIABLES``, ``ELEMENT LIE VARIABLES``, ``NODE VARIABLES``, and ``GLOBAL VARIABLES``. If any of these commands are used then all default variable transfers will be deactivated and all desired transfer variables *must be manually specified*.

The ``ELEMENT LIE VARIABLES`` designation indicates that variables should undergo a specialized mapping for interpolation to preserve their spaces.  Specifically, a logarithmic mapping of the scalar, vector, or tensor field is performed before any transfer operation is initiated. The logarithmically mapped fields are transferred and interpolated to the elements of the receiving mesh, after which the values are exponentially mapped. This transfer method is more accurate, and appropriate for only variables that belong to Lie groups. In practice, these variables include rotations, deformation gradients, and stretches. The ``ELEMENT LIE VARIABLES`` option is valid only when an :math:`L_2` projection transfer is specified.

.. warning::

   Manual selection of element variables is only functional with :math:`L_2` projection transfer.

Additional Transfer Options
===========================

Additional procedural transfer options include the ability to specify the ``absolute search tolerance``. The ``absolute search tolerance`` is the absolute amount that the search bounding box should be expanded in each of the six global directions (+/- x, y, and z) for variable transfers. This tolerance is applied to the sending region to determine which sending mesh objects (nodes or elements) contain, or are nearby, each receiving mesh object. If the bounding box search returns zero or multiple sending mesh objects, then a more expensive inverse isoparametric mapping search routine is invoked. The default ``absolute search tolerance`` is 1.0e-5.

Additional procedural transfer options include the ability to specify the ``search bounding box inflation factor``. When performing a procedural transfer, a search is performed to determine the appropriate nodes and elements to transfer from and to. This involves performing an initial coarse bounding box search to determine which nodes and elements overlap on the send and receive mesh. By default, the bounding boxes are constructed to be the size of the element plus an inflation factor of 0.1. The ``search bounding box inflation factor`` command allows one to override the default inflation factor of 0.1 to a user specified value. This is especially useful when nodes on the receiving mesh lie outside of elements on the sending mesh.

Interpolating Data with Interpolation Transfers
===============================================

When different finite element models are used by the sending and receiving regions, or when it is desired to transfer data for rigid bodies, the ``INTERPOLATION TRANSFER`` or ``L2_PROJECTION TRANSFER`` must be used. The ``INTERPOLATION TRANSFER`` uses a local interpolation patch. The ``L2_PROJECTION TRANSFER`` relies on extrapolation of element fields to nodes and interpolation of those fields back to elements, which involves solving a global minimization problem. Generally, the ``L2_PROJECTION TRANSFER`` is more accurate. For both the ``INTERPOLATION TRANSFER`` and ``L2_PROJECTION TRANSFER``, nodal variables are interpolated from the sending mesh to the receiving mesh.

The ``TRANSFORMATION TYPE`` command inside of ``INTERPOLATION TRANSFER`` has the following options:

- ``NONE`` (default) Do interpolation with no special transformation.

- ``RIGIDBODY`` Transfer the rigid body information of each rigid body separately. Specify one and only one block in the ``SEND BLOCKS`` and ``RECEIVE BLOCKS`` line commands.

- ``REFLECT`` Transform from a half-symmetric sending model to a full receiving model.

- ``WEDGE23D`` Transform from a sending axisymmetric wedge model to a receiving full 3D cylinder model.

The ``TRANSFORMATION TYPE`` command inside of ``L2_PROJECTION TRANSFER`` has the following options:

- ``ELEMENT2ELEMENT`` Project element variables from the elements to the nodes of the sending model, transfer these projected nodal values from the sending to the receiving model via the normal interpolation transfer, then interpolate these nodal values to element variables on the receiving model. For continuous fields, this is generally the most accurate transfer method. This transfer type is combined with Lie algebra for variables belonging to Lie groups to preserve spaces of such variables.

There is no default for transformation type in ``L2_PROJECTION TRANSFER`` and one of the options must be specified.

When transferring data for non-rigid body blocks, the only required line commands are the ``SEND BLOCKS|SEND ASSEMBLIES`` and ``RECEIVE BLOCKS|RECEIVE ASSEMBLIES``  line commands. These each list one or more blocks to be included in the transfer.

Interpolation transfers move data from sending to receiving meshes by performing searches and interpolating values using shape functions. Interpolation transfers will give the most accurate results when the sending and receiving meshes are similar. If the sending and receiving meshes do not occupy the same 3D space, for instance, transferred data is likely to be highly inaccurate.

In some instances, the sending and receiving meshes are highly similar such that there is a one-to-one correspondence between the list of sending blocks and the list of receiving blocks. In other words, it may be desired to send data from a given block to a corresponding block, from another block to its pair, and so forth. If this is the case, use of the ``BLOCK BY BLOCK`` line command will cause a separate transfer to be created for each pair of sending and receiving blocks. This is useful to ensure that data from a single block will be sent to one and only one receiving block. This could also be accomplished by listing multiple transfer blocks in the input file. Note that  if using the ``BLOCK BY BLOCK`` line command, the names of the blocks listed in ``SEND BLOCKS`` and ``RECEIVE BLOCKS`` or contained in the assemblies listed in ``SEND ASSEMBLIES`` and ``RECEIVE ASSEMBLIES`` must be identical.

For certain use cases, such as remeshing for large deformations, it is desired to remesh on the deformed (current) configuration and adopt that as the new reference (model) configuration. For these use cases, use the command ``SEND COORDINATES = CURRENT`` instead of the default ``SEND COORDINATES = ORIGINAL`` so that the current configuration of the sending mesh is mapped to the model configuration of the receiving mesh when performing the search used by the transfers. Displacements are not transferred for this use case since deformations are assumed to be accounted for in the receiving mesh, i.e., the mesh was generated on the deformed configuration.

.. warning::

   Adoption of a new reference configuration on the receiving mesh is currently only compatible with midpoint strain increment element formulations and hypo-elastic material models. All other element formulations and hyper-elastic materials require a multiplicative decomposition of the deformation gradient: the deformation gradient mapped from the sending mesh pre-multiplied by the deformation gradient due to the subsequent deformation applied on the receiving mesh. Such a multiplicative decomposition is not currently supported in transfers at this time.

Nodal variable interpolation transfer
-------------------------------------

The location of each receiving node in the receiving mesh is used to find a corresponding element in the sending mesh. The parametric coordinates of the coordinates associated with the receiving node within (or near) the sending element are calculated and subsequently used in conjunction with the element shape functions to interpolate the sending element nodal data onto each receiving node.

Nodal variables are always transferred using an ``INTERPOLATION TRANSFER``. The ``NODAL TRANSFER TYPE`` command determines the send and receive sets over which nodal variables interpolate and has the following options:

- ``INTERPOLATE`` (default for ``L2_PROJECTION TRANSFER``) Nodal variables are transferred between the send and receive blocks defined within the same transfer.

- ``GLOBAL_INTERPOLATION`` (default for ``INTERPOLATION TRANSFER``) Nodal variables are transferred between all send and receive blocks in the mesh.

Element variable interpolation transfer
---------------------------------------

In an ``INTERPOLATION TRANSFER`` block, the center of each receiving element will be located within (or near) the closest element in the sending mesh. A patch of elements in the sending mesh centered around the element containing the receiving element center is created. The receiving element value is then computed by interpolating the data in this patch of sending elements, using a least squares approach, to the point associated with the receiving element.

When the ``NEAREST ELEMENT COPY`` line command is used, data is sent directly from the closest sending element to the receiving element, forgoing the patch construction and least squares interpolation. A ``NEAREST ELEMENT COPY`` transfer is expected to be faster but potentially less accurate than an ``INTERPOLATION TRANSFER``.

Reflection (REFLECT) transfer
-----------------------------

Simulation results from a half-symmetry model may be transferred onto a full geometry receiving mesh using the ``REFLECT`` interpolation transfer. The reflection plane must be on one of the global coordinate planes defined ``XY``, ``YZ``, or ``ZX``. This plane should be additionally specified with the ``REFLECT PLANE = XY|YZ|ZX`` command.

Wedge-to-3D (WEDGE23D) transfer
-------------------------------

Simulation results from an axisymmetric wedge submodel may be transferred  onto a full geometry using the ``WEDGE23D`` interpolation transfer. The  ``WEDGE23D`` transfer will transforms vector and tensor quantities as  appropriate during the interpolation. One of the wedge faces should lie on  a global coordinate plane to use this transfer type. Several additional commands  may be used to further specify the transfer:

- ``W23D ANGLE`` The wedge angle should be provided in degrees. This command is used to determine how the submodel data is rotated and interpolated onto the  full model.

- ``W23D PLANE`` The location of the wedge and the cylindrical axis used to revolve the wedge during reconstruction is specified as one of ``XY|XZ|YX|YZ|ZX|ZY``. The first letter identifies the cylindrical axis. For example: if the wedge submodel is meshed with one of the wedge faces on the ``YX`` plane, and the wedge should be revolved around the y-axis to obtain the full geometry, then one should select the ``YX`` option rather than the ``XY`` option.

- ``W23D REVOLVE ANGLE`` The revolve angle command specifies the total angle,  in degrees, of the target geometry. This value should be an integral multiple of the  ``W23D ANGLE``. In practice, this might be useful for reconstructing a quarter-symmetry  or half-symmetry model from a smaller wedge.

Element variable :math:`L_2` projection transfer
------------------------------------------------

In an ``L2_PROJECTION`` transfer block, element variables at the numerical quadrature points of the sending mesh are first projected, via a global least squares solution, to the nodes of the sending mesh. A nodal interpolation transfer (described above) is then performed to transfer data from the nodes of the sending mesh to nodes of the receiving mesh. Finally, nodal data on the receiving mesh is interpolated to the quadrature points of the receiving mesh. A :math:`L_2` projection transfer is expected to yield more accurate element fields than an interpolation transfer.

For each block specified in ``SEND BLOCKS``, or contained in the assemblies  specified in ``SEND ASSEMBLIES``, a separate linear system, based on the consistent mass matrix (refer to :numref:`output-results-extrapolate` for details), is assembled and solved. Each element variable is projected to a nodal variable unique to the sending block so that potentially discontinuous fields at neighboring block boundaries are handled consistently.

In :math:`L_2` projection transfers based on higher-order element topologies such as ten-noded tetrahedra, the topology is transformed into an equivalent linear topology for extrapolation. Extrapolated nodal values are then linearly interpolated to the high-order nodes. This strategy has been shown to avoid spurious oscillations in the extrapolated quantities.

A particular linear solver may be selected for the :math:`L_2` projection using the ``LINEAR SOLVER`` user output command. The default is "DEFAULT_FETI_SOLVER."  Care should be taken to specify appropriate solver parameters and tolerances for the desired accuracy of the projection. Loose tolerances can significantly degrade the mapped solution. Generally, transfers consume a small percentage of the total run time, so a tight residual tolerance (e.g., :math:`10^{-12}`) is recommended.

The formation of the L2 projection matrix can be controlled via the ``PROJECTION TYPE`` command. The default value ``CONSISTENT`` constructs an L2 projection matrix through a consistent evaluation of the shape functions, which must subsequently be used with a linear solver to obtain the nodal values. The alternative options ``ROW_SUM_LUMPED``  and ``PROPORTIONAL_LUMPED`` use lumping schemes (row-sum lumping or diagonal proportional lumping schemes) to diagonalize the projection matrix. As a result, no iterative linear solve is necessary and the solver provided by ``LINEAR SOLVER`` is not used. This may be  useful in specific cases where the iterative linear solver fails in parallel solutions.
