9.1. Syntax for Requesting Variables

The basic method of requesting output is done by specifying the output type (nodal, element, or global), followed by the name of the variable. The original name will now appear in the output file, or the variable may be renamed using the as specifier.

var_type(element,nodal,global) <string>var_name

Variables may be accessed in the code either in whole or by component. Values at specific components or integration points of multi-component variables may be accessed via parenthesis syntax. Parenthesis syntax may be applied to results output, history output, element death, or any other command where variable names are specified. Values of single-component variables indexed in some other way may be accessed with underscore syntax, primarily applicable to rigid body fields as discussed in Section 9.1.4.

Parenthesis syntax is a variable name of the form:

<string>var_name(<index>component,<integer>integration_point)

For a variable named var, a variable name of the form var(A,B) asks for the A component of the variable at integration point B. If a variable is a vector, x, y, or z may be specified as the component. If a variable is \(3\times 3\) tensor, xx, yy, zz, xy, xz, yz, yx, zx, or zy may be specified as the component. Components for other types of variables may be requested through an integer index.

The characters : and * are wild cards if used for specifying either the component or the integration point. var(:,B) asks for all components of var at integration point B. var(A,:) asks for component A of var at all integration points. var(:,:) asks for all components of var at all integration points. var is shorthand for var(:,:).

var(A) will behave slightly differently depending on the nature of the variable. If the variable has multiple components, then Var(A) is treated like var(A,:). If a variable has one and only one component then it is assumed that A refers to the integration point number rather than the component number and Var(A) is treated like var(1,A).

9.1.1. Example 1

Let stress be a tensor defined on a single integration point element and a displacement vector be defined at all model nodes. The following output variable specification:

element stress as str
nodal displacement as disp

asks for all the components of the stress tensor on elements and all components of the displacement vector on nodes. The code would write these variables to the output file:

str_xx
str_yy
str_zz
str_xy
str_xz
str_yz
disp_x
disp_y
disp_z

If only the yy component of stress is desired, either of the following could be used:

element stress(yy) as my_yy_str1
element stress(2) as my_yy_str2

If only the z component of displacement is desired either of the following could be specified:

nodal displacement(z) as my_z_disp1
nodal displacement(3) as my_z_disp2

Note, tensor index 2 corresponds to the yy component of the tensor and vector index 3 corresponds to the z component of the vector.

9.1.2. Example 2

Let unrotated_stress be a tensor defined at each of three integration points of an element (e.g., a shell element), and eqps a scalar material state variable also defined at each element integration point. To request all unrotated_stress tensor components and all eqps scalar data at all integration points the following could be specified:

element unrotated_stress as str
element eqps as eqps

Which would output the variables:

str_xx_1, str_yy_1, str_zz_1, str_xy_1, str_xz_1, str_yz_1
str_xx_2, str_yy_2, str_zz_2, str_xy_2, str_xz_2, str_yz_2
str_xx_3, str_yy_3, str_zz_3, str_xy_3, str_xz_3, str_yz_3
eqps_1, eqps_2, eqps_3

To request the unrotated_stress tensor and value of eqps at the second integration point, the following syntax can be used:

element unrotated_stress(:,2) as str_intg2
element eqps(2) as eqps_intg2

This would output the variables:

str_intg2_xx
str_intg2_yy
str_intg2_zz
str_intg2_xy
str_intg2_xz
str_intg2_yz
eqps_intg2

To request the xy component of unrotated_stress at all integration points any of the following could be used:

element  unrotated_stress(xy,*) as str_xy_all
element  unrotated_stress(xy,:) as str_xy_all
element  unrotated_stress(xy)   as str_xy_all

Any of the above would output:

str_xy_all_1
str_xy_all_2
str_xy_all_3

9.1.3. Other command blocks

The parenthesis syntax described above for results output can also be used in most other commands involving variable names. For example, to kill elements based on \(yy\) component of stress or \(z\)-displacement the following could be specified:

begin element death
  criterion is element value of stress(yy) > 1000
  criterion is average nodal value of displacement(z) > 3.0
end

9.1.4. Rigid Body Variables

Rigid body variables are provided as separate components of the rigid body fields, which may be accessed by outputting the desired field component(s). To access the field component of rigid bodies, an underscore syntax is employed (the parenthesis syntax applies to multi-component fields and integration points). The underscore syntax takes the desired field component and appends it with an underscore and the desired rigid body name.

For example the following lines in a history output block (see Section 9.6)

global ax_rb1
global displz_rb4

would output to the history file the variables

ax_rb1
displz_rb4

which are the translational acceleration in the \(x\)-direction of rigid body rb1 and the translational displacement in the \(z\)-direction of rigid body rb4, respectively (see Table Table 9.5).