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 User_Subroutine

   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}  ]

   Select One Receiver For Each Send Object

   Select One Unique Receiver For Each Send Object

   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 User_Subroutine
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: Basis functions for nodal fields and a neighborhood least squares fit for element fields. This line command can be used to override this if needed. It also allows an application to register it’s own special interpolation functions that can then be used if the special name it was registered with is known.

Parameter	Value	Default
User_Subroutine	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}	–

Select One Receiver For Each Send Object

Syntax

Select One Receiver For Each Send Object

Summary

This option will cause each sending object to be used once and only once. This will have the side effect of some receiving objects not getting any value at all. If you use this option, you will also want to set

NODES OUTSIDE REGION IGNORE

The example which necessitated this option was a case in which there was a delta function defined on an element in the sending mesh. It was desirable that the delta functions be summed into the receiving mesh such that the total value of the sending was conserved. It was better to have only a single element on the receiving side have a non-zero value that was the sum of sending values and not worry about how close the receiving element was to the sending element. A check that this option is working is to use Encore to computer the sum of the values of the sending and receiving fields to make sure the total sum is the same.

Select One Unique Receiver For Each Send Object

Syntax

Select One Unique Receiver For Each Send Object

Summary

An unusual flag to get around an odd problem. Normally each receive object transfers from the nearest sending object so it is almost always the case that a send object will be used multiple times to define a receiving value. This option will cause each sending object to be used only once. This will have the side effect of some receiving objects not getting any value at all. If you use this option, you will also want to set

NODES OUTSIDE REGION IGNORE

or else the uniqueness will be lost for nodes outside the sending region. The example which necessitated this option was a case in which there was a delta function defined on an element in the sending mesh. It was desirable that the delta function be defined on the receiving mesh for only a single element in the neighborhood of the sending element. The analysis was more sensitive to the number of delta functions on the receiving side than the location. So it was better to have only a single element on the receiving side have a non-zero value and not worry about how close the receiving element was to the sending element.

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

Scope: Transfer
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

Scope: Transfer
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…	–