10.1. User Variables

BEGIN USER VARIABLE <string>var_name
  BLOCK = <string list>block_names
  ASSEMBLY = <string list>assembly_names
  TYPE = <string>NODE|ELEMENT|GLOBAL
    [<string>REAL|INTEGER LENGTH = <integer>length]|
    [<string>SYM_TENSOR|FULL_TENSOR|VECTOR]
  GLOBAL OPERATOR = <string>SUM|MIN|MAX
  INITIAL VALUE = <real list>values
  INITIAL VARIATION = <real list>values LINEAR DISTRIBUTION
  USE WITH RESTART
END [USER VARIABLE <string>var_name]

The USER VARIABLE command block is used to create a user-defined variable. This kind of variable may be used for scratch space in a user subroutine or for some user-defined output. A user-defined variable may be output to the results file or the history file just like any other defined variable; i.e., a user-defined variable once defined by the USER VARIABLE command block can be specified in a USER OUTPUT command block, a RESULTS OUTPUT command block, and a HISTORY OUTPUT command block.

User-defined variables are associated with mesh entities: a node variable will exist on the nodes, an element variable will exist on the elements, and a global variable will have a single value for the entire model. By default, the variable is registered on the entire model, but the BLOCK|ASSEMBLY command can be used to register the variable on a subset of the model. The BLOCK|ASSEMBLY command enables registering a variable with different numbers of components between blocks, such as an element variable with LENGTH = 1 on a block with mean-quadrature linear hexahedra and LENGTH = 8 on another block with fully-integrated linear hexahedra. Assemblies may contain blocks, or assemblies of these.

If the user-defined variable functionality is used in conjunction with restart, the USE WITH RESTART command line must be included.

The USER VARIABLE command block is placed within a Sierra/SM region. The command block begins with the input line:

BEGIN USER VARIABLE <string>var_name

and ends with the input line:

END [USER VARIABLE <string>var_name]

where var_name is a user-selected name for the variable.

In the above command block:

  • A user-defined variable has an associated type that is specified by the TYPE command line, which itself contains several parameters. The TYPE command line is required.

  • The variable must be a nodal quantity, an element quantity, or a global quantity. The options NODE, ELEMENT, and GLOBAL determine whether the variable will be a nodal, element, or global quantity. One of these options must appear on the TYPE command line.

  • The user-defined variable can be either an integer or a real, as specified by the INTEGER or REAL option.

  • The length of the variable must be set by using one of the options SYM_TENSOR, FULL_TENSOR, VECTOR, or LENGTH = <integer>length. If the LENGTH option is used, the user must specify whether the variable is an integer number or a real number by using the INTEGER or REAL option. If the SYM_TENSOR option is used, the variable has six real components. If the FULL_TENSOR is used, the variable has nine real components. If the VECTOR option is used, the variable has three real components. The three options SYM_TENSOR, FULL_TENSOR, and VECTOR all imply real numbers, and thus the REAL option need not be included in the command line when one of these three options is specified.

Some examples of the TYPE command line follow:

type = global real length = 1
type = element tensor
type = element real length = 3
type = node sym_tensor
type = node vector

  • If you use the GLOBAL option on the TYPE command line, a global variable is created, and this global variable must be given an associated reduction type, which is specified by the GLOBAL OPERATOR command line. The reduction type tells Sierra/SM how to reduce the individual values stored on each processor to a mesh global value. Global reductions are performed at the end of each time step. The SUM operator sums all processor variable contributions. The MAX operator takes the maximum value among all processor variable contributions. The MIN operator takes the minimum value among all processor variable contributions.

  • One or more initial values may be specified for the user-defined variable in the INITIAL VALUE command line. The number of initial values specified should be the same as the length of the variable, as specified in the TYPE command line either explicitly via the LENGTH option or implicitly via the SYM_TENSOR, FULL_TENSOR, or VECTOR option. The initial values will be copied to the variable space on every mesh object on which the variable is defined. Only real type variables may be given initial values at this time.

  • The initial value of the user variable can be given some random distribution by use of the INITIAL VARIATION command line. If the INITIAL VARIATION command is used the INITIAL VALUE command must also be used. In addition the number of values specified in the initial variation command must exactly match the number of values specified in the initial value command. When the initial variation command is used the initial values of the variable will be set as initial value plus or minus some random factor times the initial variation. Currently the only random distribution supported is the linear distribution. With linear distribution the random values will be distributed evenly from initial value minus variation to initial value plus variation.

  • All intrinsic type options such as REAL, INTEGER, SYM_TENSOR, FULL_TENSOR, VECTOR and the LENGTH option can be used with any of the mesh entity options (NODE, ELEMENT, GLOBAL).

  • As indicated previously, if the user-defined variable functionality is used in conjunction with restart, the USE WITH RESTART command line must be included.