.. _output-syntax:

*******************************
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.

.. code-block:: sierrainput

   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 :numref:`output-rb_varoutput`.

Parenthesis syntax is a variable name of the form:

.. code-block:: sierrainput

   <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 :math:`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)``.

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:

.. code-block:: sierrainput

   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:

.. code-block:: sierrainput

   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:

.. code-block:: sierrainput

   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:

.. code-block:: sierrainput

   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.

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:

.. code-block:: sierrainput

   element unrotated_stress as str
   element eqps as eqps

Which would output the variables:

.. code-block:: sierrainput

   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:

.. code-block:: sierrainput

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

This would output the variables:

.. code-block:: sierrainput

   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:

.. code-block:: sierrainput

   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:

.. code-block:: sierrainput

   str_xy_all_1
   str_xy_all_2
   str_xy_all_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 :math:`yy` component of stress or :math:`z`-displacement the following could be specified:

.. code-block:: sierrainput

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

.. _output-rb_varoutput:

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 :numref:`output-history`)

.. code-block:: sierrainput

   global ax_rb1
   global displz_rb4

would output to the history file the variables

.. code-block:: sierrainput

   ax_rb1
   displz_rb4
  
which are the translational acceleration in the :math:`x`-direction of rigid body ``rb1`` and the translational displacement in the :math:`z`-direction of rigid body ``rb4``, respectively (see Table :numref:`tab-output-variables-rb_globvars`).
