7.12. User Variables

7.12.1. User Variable

Scope: Aria Region, Equation System, Explicit Equation System, Root Finder Equation System
Summary: Defines user-named registered variables for this region. The name of the variable is specified by the line parameter ‘name’.
Description: This command block allows the user to define their own variables, which have the same status as pre-existing variables. For example, they may be output in the same way as other Aria variables, and may participate in SIERRA restart services. This feature is useful when a user has a need to store data on each mesh object (e.g. nodes) or wishes to evaluate a scalar quantity that requires parallel reduction across processors (e.g. a sum). Typically, a user variable would be set by a SIERRA framework transfer service from another region, or via user subroutines.

begin User Variable Name

   Add Part part...

   Get Global From Region other_region RemoteVariable Index

   Global Operator {=} {max | min | sum}

   Initial Value {=} Value...

   Read Variable {=} Variable [ At Time TimeValue  ]

   Reset On {iteration | step}

   Type {=} {edge | element | face | global | node} {integer | real | real_tensor | real_vector} [ Length {=} Length  ]

   Use With Restart

end User Variable Name

7.12.1.1. Line Commands

Add Part

Syntax: Add Part part…
Summary: Adds surface, block or mesh group, by name, to a user variable’s extent.
Description: This line command is used to add surfaces or blocks to the extent of a user variable. In Exodus II, surfaces are specified as side sets, that have a global integer identifier. For example, side set 12 would be added by this line command using the surface name surface_12. Similarly element blocks also have a global identifier. Note that in SIERRA, each element of an array of strings must be separated by whitespace.

Parameter	Value	Default
part	string…	–

Get Global From Region

Syntax: Get Global From Region other_region RemoteVariable Index
Summary: Specifies the user global variable value will be assigned the value of the named RemoteVariable retrieved from another application Region. Index is an offset into the RemoteVariable.

Parameter	Value	Default
other_region	string	–
RemoteVariable	string	–
Index	integer	–

Global Operator

Syntax

Global Operator {=} {max | min | sum}

Summary

REQUIRED for GLOBAL variables. Since global variables are often used in user subroutines a need arises in parallel simulations to resolve a representative single GLOBAL variable value across processors. The choice of operator determines how the single global value is to be resolved from each of the individual processor local values of the variable.

For SUM the local global variable values on each processor are summed to obtain a single value of the global variable.

For MIN the local global variable values on each processor are compared and the minimum value over all processors is assigned to the global variable.

For MAX the local global variable values on each processor are compared and the maximum value over all processors is assigned to the global variable.

Parallel synchronization of the single global variables will occur both at the beginning of a nonlinear solution iteration and at the completion of a nonlinear step. Once the synchronization has occurred the local global variable is reset to its initial value.

Parameter	Value	Default
{=}	{= \| are \| is}	–
UserVarOperator	{max \| min \| sum}	–

Initial Value

Syntax: Initial Value {=} Value…
Summary: Optional. Specifies the initial value of the user variable. The number of initial values specified with this line command must match the length of the variable specified in the “TYPE” command. If this command is present the specified initial value will automatically be applied to the user variable.

Parameter	Value	Default
{=}	{= \| are \| is}	–
Value	real…	–

Read Variable

Syntax: Read Variable {=} Variable [ At Time TimeValue ]
Summary: Requests that the variable will be assigned from a time plane of the input ExodusII database. If an AT TIME is not specified, the time plane defaults to the last time plane in the database.

Parameter	Value	Default
{=}	{= \| are \| is}	–
Variable	string	–

Reset On

Syntax: Reset On {iteration | step}
Summary: Specifies when the user global variable will be reset. By default global variable will be reset after the nonlinear step has converged.

Parameter	Value	Default
Assign	{iteration \| step}	–

Type

Syntax: Type {=} {edge | element | face | global | node} {integer | real | real_tensor | real_vector} [ Length {=} Length ]
Summary: This line command is required. The type of user variable is either real or integer, and is either a single, global value, or is associated with each mesh object of the specified kind. Global variables must have a ‘GLOBAL OPERATOR’ command associated with them to define its synchronization. The default length is 1. The default initial value for global variables is 0.

Parameter	Value	Default
{=}	{= \| are \| is}	–
UserVarMeshObject	{edge \| element \| face \| global \| node}	–
UserVarType	{integer \| real \| real_tensor \| real_vector}	–

Use With Restart

Syntax: Use With Restart
Summary: Optional. The default behavior is for user-defined variables to not be preserved across a restart. The presence of this line command specifies that the variable is to be written to and restored from the restart file.