# 7.9. Transfer

This section is referenced in the following other sections

- Simulation Setup: Transfer

## 7.9.1. Transfer

Scope

  Procedure

Summary

  Transfer region/mesh information. The mechanics/variables information will get sorted out by the calling procedure.

    begin Transfer Transfer_name

       Abort If Field Not Defined On Copy Transfer Send Or Receive Object

       Abort If Search Object Outside Of Tolerance

       All Fields

       Copy {surface | volume} {constraints | elements | nodes} From From_region_name To To_region_name

       Distance Function Is Closest Receive Node To Send Centroid

       Exclude Ghosted

       From {constraints | elements | nodes} To {constraints | elements | faces | gauss_points | nodes}

       Gauss Point Integration Order {=} Order

       Geometric Tolerance {=} Geometric_tolerance

       Inspect With File {=} File_name Ids {=} ID_list...

       Interpolate {surface | volume} {constraints | elements | nodes} From From_region_name To To_region_name

       Interpolation Function Function_Name

       Nodes Outside Region {=} {abort | extrapolate | ignore | project | truncate}

       Parametric Tolerance {=} Parametric_tolerance

       Patch Recovery Evaluation {=} {linear least squares | linear moving least squares | quadratic least squares | quadratic moving least squares}

       Search Coordinate Field Source_field_name State {new | nm1 | nm2 | nm3 | nm4 | none | old} To Destination_field_name State {new | nm1 | nm2 | nm3 | nm4 | none | old}

       Search Geometric Tolerance {=} Geometric_tolerance

       Search Surface Gap Tolerance {=} Surface_gap_tolerance [ Or Less  ]

       Search Type {=} [ {detailed | parallel | proximity} {detailed | parallel | proximity} {detailed | parallel | proximity}  ]

       Send {} Fields

       Send Block From_blocks... To To_blocks...

       Send Field Source_field_name State {new | nm1 | nm2 | nm3 | nm4 | none | old} To Destination_field_name State {new | nm1 | nm2 | nm3 | nm4 | none | old} [ Lower Bound Lower_bound Upper Bound Upper_bound  ]

       Toggle Search Warnings {=} {false | no | off | on | true | yes}

       Use Centroid For Geometric Proximity

       begin Receive Blocks
       end

       begin Send Blocks
       end

    end Transfer Transfer_name

### 7.9.1.1. Line Commands

###### Abort If Field Not Defined On Copy Transfer Send Or Receive Object

Syntax

  Abort If Field Not Defined On Copy Transfer Send Or Receive Object

Summary

  For testing purposes only. Normally mesh objects in the send or receive mesh which do not have the specified field defined on them are just ignored. This line command allows the construction of tests in which it is known that every mesh object should have the specified field defined on it and to abort if that field is not found.

###### Abort If Search Object Outside Of Tolerance

Syntax

  Abort If Search Object Outside Of Tolerance

Summary

  For debugging purposes only. Abort transfer if search object lie outside of specified geometric tolerance.

  This command is deprecated. Use “Nodes outside region = abort” instead.

###### All Fields

Syntax

  All Fields

Summary

  Select all fields for transfer that have same name and state for source and destination regions.

###### Copy

Syntax

  Copy {surface | volume} {constraints | elements | nodes} From From_region_name To To_region_name

Summary

  Copy transfer elements, nodes or constraints from one region to another. The copy transfer is very specific in that the sending and receiving mesh parts must have identical global ids for every element to be copied. The copy transfer works by iterating over all the mesh objects in the receiving mesh and using the global id of the receiving mesh object to find a mesh object in the sending mesh with the same global id. The field to transfer is then copied from the sending to receiving objects. There is no interpolation and the actual coordinates of the sending and receiving objects are not used and could be very different. The copy transfer is used in very special cases where the same mesh was read into both the sending and receiving meshes, there was no element death and there was no adaptivity. In this special case, a copy transfer can be much faster than an interpolation transfer.

Parameter | Value | Default
--- | --- | ---
Option1 | {surface | volume} | –
Option2 | {constraints | elements | nodes} | –
From_region_name | string | –
To_region_name | string | –

###### Distance Function Is Closest Receive Node To Send Centroid

Syntax

  Distance Function Is Closest Receive Node To Send Centroid

Summary

  To be used in conjunction with “SELECT ONE UNIQUE RECEIVER FOR EACH SEND OBJECT”. This helped in the case where the sending and receiving element blocks did not overlap and an element transfer was using element centroids for the distance computation. The elements were very distorted so that a centroid of a surface element could be far from the surface. It was wanted that the receiving element be the one close to the surface of the block and close to the sending element in the adjacent block. Using the corner nodes was enough since it was a tet mesh with plane faces. In this particular and unusual case this alternative method of matching sending and receiving elements was useful, but it is not expected to be used often or maybe never again.

###### Exclude Ghosted

Syntax

  Exclude Ghosted

Summary

  exclude ghosted nodes from a copy transfer

###### From

Syntax

  From {constraints | elements | nodes} To {constraints | elements | faces | gauss_points | nodes}

Summary

  Allows the send/receive mesh objects to be different. For a volume element field transfer (e.g. shell) to a face rank field on a surface, use ‘from elements to faces’.

Parameter | Value | Default
--- | --- | ---
Option1 | {constraints | elements | nodes} | –
Option2 | {constraints | elements | faces | gauss_points | nodes} | –

###### Gauss Point Integration Order

Syntax

  Gauss Point Integration Order {=} Order

Summary

  Integration order to use when transferring to Gauss points.

Parameter | Value | Default
--- | --- | ---
{=} | {= | are | is} | –
Order | integer | –

###### Geometric Tolerance

Syntax

  Geometric Tolerance {=} Geometric_tolerance

Summary

  This is the dimensional tolerance applied during the initial (coarse) search. If specified, all the coarse search boxes are padded by this value. The default behavior is for this to be 1e-9 times the problem bounding box size (diagonal) plus a 10 percent relative expansion per element. If a value is specified for this, it is used as a padding in place of the default with no relative box expansion.

  During the interpolation transfer there is a geometric search based on the coordinates of the send and receive objects. As part of this search, an axis aligned bounding box is contracted for each sending object and GEOMETRIC TOLERANCE is used to make this box bigger than just a tight bounding box. Lists of receiving points are then quickly found within these axis aligned boxes.

  If all points in the receiving mesh are within at least one box, no additional searching needs to be done and the search algorithm is fast. If there are still points in the receiving mesh that were outside of EVERY box, then a warning message will be issued about an “expensive search for extrapolation” for these points. This ‘expensive search” can be very costly if a large number of receiving objects fall into this category and this line command is provided for those special cases.

Parameter | Value | Default
--- | --- | ---
{=} | {= | are | is} | –
Geometric_tolerance | real | –

###### Inspect With File

Syntax

  Inspect With File {=} File_name Ids {=} ID_list…

Summary

  STK Transfer inspection tool that allows user to output the search results for a specified list of entity ids on the receive mesh. The rank of the entities is deduced from the type of transfer being set up.

Parameter | Value | Default
--- | --- | ---
{=} | {= | are | is} | –
File_name | string | –
{=} | {= | are | is} | –
ID_list | integer… | –

###### Interpolate

Syntax

  Interpolate {surface | volume} {constraints | elements | nodes} From From_region_name To To_region_name

Summary

  Interpolate will transfer elements, nodes or constraints from one mesh to another. The interpolation transfer is very general in that the field values to transfer will be interpolated from the sending to receiving mesh based on the coordinates of the sending and receiving mesh objects.

  Many line commands can be used to modify the behavior of the interpolation transfer but the basic algorithm is straightforward. Every mesh object in the receiving mesh is converted into a point. For elements this is the average of the nodal coordinates. An element in the sending mesh containing this point is found. If the field to transfer is nodal, the element shape functions are used to interpolate the nodal field to the receiving point. If the field to transfer is elemental, a bi-linear least squares fit based upon neighboring elements is first performed and then used to define the interpolation of the element field at the receiving point.

Parameter | Value | Default
--- | --- | ---
Option1 | {surface | volume} | –
Option2 | {constraints | elements | nodes} | –
From_region_name | string | –
To_region_name | string | –

###### Interpolation Function

Syntax

  Interpolation Function Function_Name

Summary

  Allows an application defined subroutine to be used for the interpolation. Normally the interpolation transfer will determine the best type of interpolation to use for node or element entities: Basis functions for nodal fields and a neighborhood least squares fit for element fields. This command line can be used to override the default behavior if needed. Available interpolation functions are Sum, Copy, Master_Element, Element_Centroid_Constant and Element_Centroid_Linear.

  Sum - Sum surrounding entity values on source and send to destination.

  Copy - Copy entity values directly from source to destination.

  Master_Element - Send interpolated nodal values from nearest source element to destination.

  Element_Centroid_Constant - For nodal field transfer send computed centroid value from the nearest source element to destination. For element field transfer send the element field value from the nearest source element to the destination

  Element_Centroid_Linear - Send values of interpolated centroid values obtained using patch recovery to destination. Patch recovery involves a least squares reconstruction and evaluation using a patch of elements surrounding the nearest source element. For linear and higher-order reconstructions one should consult the Patch Recovery Evaluation option.

Parameter | Value | Default
--- | --- | ---
Function_Name | string | –

###### Nodes Outside Region

Syntax

  Nodes Outside Region {=} {abort | extrapolate | ignore | project | truncate}

Summary

  This line command defines what to do when a receiving point is outside the scope of the sending mesh.

  IGNORE - The receiving mesh object can be ignored and will receive no value. This is almost never a good idea as it can cause mesh objects just outside to have a zero value when the nodes just inside the mesh might have very large values. This can result in a discontinuous receiving field.

  EXTRAPOLATE - This is the default behavior. The sending field is extrapolated beyond the bounds of the sending mesh. This can lead to extrapolation error, such as when a large gradient at the surface causes a negative values when only positive values are acceptable. If this happens to the upper and lower bounds that can be placed on the fields to be transferred with the SEND FIELD command.

  TRUNCATE - The receiving coordinate is projected back to the surface of the sending mesh to determine a value. This ensures that the receiving value is not outside of the field values in the sending mesh.

  PROJECT - This option is similar to TRUNCATE in which the receiving coordinate is projected back to the surface of the sending mesh to determine a value. In this case more effort is made to make sure that the projection is normal to the surface in the sending mesh. Sometimes gives a better result than Truncate but is a little more expensive to compute.

  If the PROJECT option is used in transferring of surface values, the sending mesh should envelope the receiving mesh. Failure to satisfy this condition will generally result in failure of the transfer.

  ABORT - If any receiving point is outside the sending mesh by more than the geometric tolerance, abort the simulation. Do not attempt to project, extrapolate, or otherwise handle the point.

Parameter | Value | Default
--- | --- | ---
{=} | {= | are | is} | –
Option | {abort | extrapolate | ignore | project | truncate} | –

###### Parametric Tolerance

Syntax

  Parametric Tolerance {=} Parametric_tolerance

Parameter | Value | Default
--- | --- | ---
{=} | {= | are | is} | –
Parametric_tolerance | real | –

###### Patch Recovery Evaluation

Syntax

  Patch Recovery Evaluation {=} {linear least squares | linear moving least squares | quadratic least squares | quadratic moving least squares}

Summary

  This line command defines the available choices for the patch recovery and evaluation algorithm when using interpolation for element variables. The default option is Linear Least Squares.

Parameter | Value | Default
--- | --- | ---
{=} | {= | are | is} | –
Option | {linear least squares | linear moving least squares | quadratic least squares | quadratic moving least squares} | –

###### Search Coordinate Field

Syntax

  Search Coordinate Field Source_field_name State {new | nm1 | nm2 | nm3 | nm4 | none | old} To Destination_field_name State {new | nm1 | nm2 | nm3 | nm4 | none | old}

Summary

  Normally the interpolation transfers use the default coordinate field to determine geometry information. This line command can be used to specify an alternate field.

Parameter | Value | Default
--- | --- | ---
Source_field_name | string | –
Option1 | {new | nm1 | nm2 | nm3 | nm4 | none | old} | –
Destination_field_name | string | –
Option2 | {new | nm1 | nm2 | nm3 | nm4 | none | old} | –

###### Search Geometric Tolerance

Syntax

  Search Geometric Tolerance {=} Geometric_tolerance

Parameter | Value | Default
--- | --- | ---
{=} | {= | are | is} | –
Geometric_tolerance | real | –

###### Search Surface Gap Tolerance

Syntax

  Search Surface Gap Tolerance {=} Surface_gap_tolerance [ Or Less ]

Summary

  This is the dimensional tolerance applied during the initial (coarse) search. If specified, all the coarse search boxes are padded by this value. The default behavior is for this to be 1e-9 times the problem bounding box size (diagonal) plus a 10 percent relative expansion per element. If a value is specified for this, it is used as a padding in place of the default with no relative box expansion.

  This is a tricky parameter best ignored, let it default to something based on the problem size. During the interpolation transfer there is a geometric search based on the coordinates of the send and receive objects. As part of this search, an axis aligned bounding box is contracted for each sending object and SEARCH GAP TOLERANCE is used to make this box bigger than just a tight bounding box. Lists of receiving points are then quickly found within these axis aligned boxes.

  If all points in the receiving mesh are within at least one box, no additional searching needs to be done and the search algorithm is fast. If there are still points in the receiving mesh that were outside of EVERY box, then a warning message will be issued about an “expensive search for extrapolation” for these points. This ‘expensive search” can be very costly if a large number of receiving objects fall into this category and this line command is provided for those special cases.

  The OR LESS optional parameter is used when the tolerance must be set to large value for one part of the mesh but much of the mesh needs a much smaller value. In some cases it is necessary for the tolerance to be set to the actual largest surface gap tolerance which may be far too large a gap for the rest of the mesh. Setting OR LESS allows the search tolerance to be reduced in areas of the mesh thus resulting in a faster search.

Parameter | Value | Default
--- | --- | ---
{=} | {= | are | is} | –
Surface_gap_tolerance | real | –

###### Search Type

Syntax

  Search Type {=} [ {detailed | parallel | proximity} {detailed | parallel | proximity} {detailed | parallel | proximity} ]

Parameter | Value | Default
--- | --- | ---
{=} | {= | are | is} | –

###### Send

Syntax

  Send {} Fields

Summary

  Use predefined transfer semantics provided by the specified name.

Parameter | Value | Default
--- | --- | ---
Predefined-transfer | {} | –

###### Send Block

Syntax

  Send Block From_blocks… To To_blocks…

Summary

  Add element blocks to a particular same mesh element copy transfer operator.

  The copy transfer can have multiple of these lines to define many blocks, but each line sends a single block to a single block:

      SEND BLOCK block_1 TO block_1
      SEND BLOCK block_101 TO block_101

  The interpolation transfer can have only a single SEND BLOCK line, but can define many from/to blocks:

      SEND BLOCK block_3 block_5 block_6 TO block_3 block_5

Parameter | Value | Default
--- | --- | ---
From_blocks | string… | –
To_blocks | string… | –

###### Send Field

Syntax

  Send Field Source_field_name State {new | nm1 | nm2 | nm3 | nm4 | none | old} To Destination_field_name State {new | nm1 | nm2 | nm3 | nm4 | none | old} [ Lower Bound Lower_bound Upper Bound Upper_bound ]

Summary

  Specifies the mapping between source and destination field names. Vector and tensor fields can be subscripted using parenthesis and 1’s based or brackets and 0 based. Notes on subscripting:

  - Does not work for COPY transfers, only INTERPOLATION type transfers.

  - If the field name itself actually contains either parenthesis or brackets then we are in trouble and an error is going to be thrown due to a syntax error in index specification.

  - Only a single subscript is allowed so vectors of vectors or higher order tensors can not use double subscripts. But it should be possible to determine the correct offset within the field and pick out the correct value with a little effort.

  - Once subscripted, only a single value will be transferred. It is not possible to transfer multiple values starting at a certain index, instead multiple line commands must be used, as shown above.

  - The indexes can be 0 based with brackets or 1 based when using parenthesis. Although this could be very confusing if mixed within a single line command.

  - Both the from and to fields can be subscripted independently on the same line.

  example

      SEND FIELD velocity TO velocity
      SEND FIELD temp     TO temperature  lower bound 0
      SEND FIELD x        TO y lower bound 10 upper bound 100
      SEND FIELD A(2)     TO B(3) lower bound 10 upper bound 100
      SEND FIELD A[1]     TO B[2] lower bound 10 upper bound 100

Parameter | Value | Default
--- | --- | ---
Source_field_name | string | –
Option1 | {new | nm1 | nm2 | nm3 | nm4 | none | old} | –
Destination_field_name | string | –
Option2 | {new | nm1 | nm2 | nm3 | nm4 | none | old} | –

###### Toggle Search Warnings

Syntax

  Toggle Search Warnings {=} {false | no | off | on | true | yes}

Summary

  Specify whether warnings about entities outside of the search domain should be printed. The default behavior is to always print these warning messages.

Parameter | Value | Default
--- | --- | ---
{=} | {= | are | is} | –
Option | {false | no | off | on | true | yes} | –

###### Use Centroid For Geometric Proximity

Syntax

  Use Centroid For Geometric Proximity

Summary

  STK Transfer option to trigger the use of centroid based proximity comparison for selecting the best interpolating entity when receive entities lie outside of the domain. Default geometric proximity comparison is based on geometric projection which is more expensive but accurate. The use of this option is a way to reduce computational cost especially for meshes that are fairly regular. However, there is no guarantee of accuracy.

### 7.9.1.2. Receive Blocks

Summary

  I/O blocks to include in the transfer. Fields defined on these blocks will receive fields from the sending blocks.

    begin Receive Blocks

       Include All Blocks

       Include Block {=} IncludeBlockList...

       Remove Block {=} ExcludeBlockList...

    end Receive Blocks

#### 7.9.1.2.1. Line Commands

###### Include All Blocks

Syntax

  Include All Blocks

Summary

  Use this parameters definition for all blocks. Example:

      BEGIN SEND BLOCKS
        INCLUDE ALL BLOCKS
        REMOVE BLOCK = block_0 block_1
      END SEND BLOCKS

###### Include Block

Syntax

  Include Block {=} IncludeBlockList…

Summary

  List of blocks to exclude. Example:

      BEGIN SEND BLOCKS
        INCLUDE BLOCK = block_3 block_4
      END SEND BLOCKS

Parameter | Value | Default
--- | --- | ---
{=} | {= | are | is} | –
IncludeBlockList | string… | –

###### Remove Block

Syntax

  Remove Block {=} ExcludeBlockList…

Summary

  List of blocks to exclude. Example:

      BEGIN SEND BLOCKS
        INCLUDE ALL BLOCKS
        REMOVE BLOCK = block_0 block_1
      END SEND BLOCKS

Parameter | Value | Default
--- | --- | ---
{=} | {= | are | is} | –
ExcludeBlockList | string… | –

### 7.9.1.3. Send Blocks

Summary

  I/O blocks to include in the transfer. Fields defined on these blocks will be transferred to fields in the receiving blocks.

    begin Send Blocks

       Include All Blocks

       Include Block {=} IncludeBlockList...

       Remove Block {=} ExcludeBlockList...

    end Send Blocks

#### 7.9.1.3.1. Line Commands

###### Include All Blocks

Syntax

  Include All Blocks

Summary

  Use this parameters definition for all blocks. Example:

      BEGIN SEND BLOCKS
        INCLUDE ALL BLOCKS
        REMOVE BLOCK = block_0 block_1
      END SEND BLOCKS

###### Include Block

Syntax

  Include Block {=} IncludeBlockList…

Summary

  List of blocks to exclude. Example:

      BEGIN SEND BLOCKS
        INCLUDE BLOCK = block_3 block_4
      END SEND BLOCKS

Parameter | Value | Default
--- | --- | ---
{=} | {= | are | is} | –
IncludeBlockList | string… | –

###### Remove Block

Syntax

  Remove Block {=} ExcludeBlockList…

Summary

  List of blocks to exclude. Example:

      BEGIN SEND BLOCKS
        INCLUDE ALL BLOCKS
        REMOVE BLOCK = block_0 block_1
      END SEND BLOCKS

Parameter | Value | Default
--- | --- | ---
{=} | {= | are | is} | –
ExcludeBlockList | string… | –