.. _output-results:

**************
Results Output
**************

The results output capability allows the user to select some set of variables to be written to a file at various time intervals. All values for each selected variable will be written to the results file. The interval at which information is written can be changed throughout the analysis time. The name of the results file is set in the ``RESULTS OUTPUT`` command block.

.. _output-results-exodus:

Exodus Results Output File
==========================

.. parsed-literal::

   BEGIN RESULTS OUTPUT <string>results_name
     #
     # Database Commands
     DATABASE NAME = <string>results_file_name
     DATABASE TYPE = <string>database_type(exodusII)
     OVERWRITE = <string>OFF|ON|TRUE|FALSE|YES|NO
       (ON|TRUE|YES)
     TITLE <string>user_title
     PROPERTY <string>propName = <string>propVal
     TIMESERIES NAME = <string>timeseries_file_name
   
     NODE VARIABLES = <string>variable_name
       [AS <string>dbase_variable_name] ...
       <string>variable_name [AS
       <string>dbase_variable_name]
       | NODAL VARIABLES = <string>variable_name
           [AS <string>dbase_variable_name] ...
           <string>variable_name [AS
           <string>dbase_variable_name]
   
     NODESET VARIABLES = <string>variable_name
       [AS <string>dbase_variable_name] ...
       <string>variable_name [AS
       <string>dbase_variable_name]
       | NODESET VARIABLES = <string>variable_name
           [AS <string>dbase_variable_name]
           INCLUDE|ON|EXCLUDE <string list>nodelist_names
           ... <string>variable_name
           [AS <string>dbase_variable_name] INCLUDE|ON|EXCLUDE
           <string list>nodelist_names
   
     SURFACE VARIABLES = <string>variable_name
       [AS <string>dbase_variable_name] ...
       <string>variable_name [AS
       <string>dbase_variable_name]
       | SURFACE VARIABLES = <string>variable_name
           [AS <string>dbase_variable_name]
           INCLUDE|ON|EXCLUDE <string list>surface_names
           ... <string>variable_name
           [AS <string>dbase_variable_name] INCLUDE|ON|EXCLUDE
           <string list>surface_names
   
     FACE VARIABLES = <string>variable_name
       [AS <string>dbase_variable_name] ...
       <string>variable_name [AS
       <string>dbase_variable_name]
       | FACE VARIABLES = <string>variable_name
           [AS <string>dbase_variable_name]
           INCLUDE|ON|EXCLUDE <string list>surface_names
           ... <string>variable_name
           [AS <string>dbase_variable_name] INCLUDE|ON|EXCLUDE
           <string list>surface_names
   
     ELEMENT VARIABLES = <string>variable_name
       [AS <string>dbase_variable_name] ...
       <string>variable_name [AS
       <string>dbase_variable_name]
       | ELEMENT VARIABLES = <string>variable_name
           [AS <string>dbase_variable_name]
           INCLUDE|ON|EXCLUDE <string list>block_names
           ... <string>variable_name
           [AS dbase_variable_name] INCLUDE|ON|EXCLUDE
           <string list>block_names
   
     GLOBAL VARIABLES = <string>variable_name
       [AS <string>dbase_variable_name] ...
       <string>variable_name [AS
       <string>dbase_variable_name]
     OUTPUT MESH = REFINED|EXPOSED SURFACE (REFINED)
     COMPONENT SEPARATOR CHARACTER = <string>character|NONE
     INCLUDE = <string>list_of_included_entities
     EXCLUDE = <string>list_of_excluded_entities
     START TIME = <real>output_start_time
     TIMESTEP ADJUSTMENT INTERVAL = <integer>steps |explicit_mini|
     AT TIME <real>time_in INCREMENT =
       <real>time_increment_dt
     AT STEP <integer>step_begin INCREMENT =
       <integer>step_increment
     ADDITIONAL TIMES = <real>output_time1
       <real>output_time2 ...
     ADDITIONAL STEPS = <integer>output_step1
       <integer>output_step2 ...
     TERMINATION TIME = <real>termination_time_value
     SYNCHRONIZE_OUTPUT
     USE OUTPUT SCHEDULER <string>scheduler name
     OUTPUT ON SIGNAL = <string>SIGALRM|SIGFPE|SIGHUP|SIGINT|
       SIGPIPE|SIGQUIT|SIGTERM|SIGUSR1|SIGUSR2|SIGABRT|
       SIGKILL|SIGILL|SIGSEGV
     AUTO OUTPUT <string>NODAL|ELEMENT|GLOBAL|ALL USER DEFINED VARIABLES
       [IN <string>user_output_block_name_list]
   END [RESULTS OUTPUT <string>results_name]

See :numref:`output-commands` for details on the general database commands such as ``DATABASE NAME``, ``DATABASE TYPE``, ``OVERWRITE``, etc. The command ``TIMESERIES NAME`` optionally emits a time-series file containing the list of root output database filenames as they are written. This is useful for simulations on high numbers of processors with many mesh modifications that output a large number of files.

A results file, the results to be included in this file, and the frequency at which results are written may be specified using a ``RESULTS OUTPUT`` command block. The command block appears inside the region scope. More than one results file can be specified for an analysis; thus, for each results file, there will be one ``RESULTS OUTPUT`` command block. The command block begins with:

.. code-block:: sierrainput

   BEGIN RESULTS OUTPUT <string>results_name

and is terminated with:

.. code-block:: sierrainput

   END [RESULTS OUTPUT <string>results_name]

where ``results_name`` is a user-selected name for the command block. Nested within the ``RESULTS OUTPUT`` command block is a set of command lines, as shown in the block summary given above.

The other command lines that appear in the ``RESULTS OUTPUT`` command block determine the type and frequency of output information. Descriptions of these command lines follow in :numref:`output-nodevar` through :numref:`output-rowriteres`.

.. _output-nodevar:

Output Nodal Variables
----------------------

.. code-block:: sierrainput

   NODE VARIABLES = <string>variable_name
     [AS <string>dbase_variable_name] ...
     <string>variable_name [AS
     <string>dbase_variable_name]
     | NODAL VARIABLES = <string>variable_name
         [AS <string>dbase_variable_name] ...
         <string>variable_name [AS
         <string>dbase_variable_name]

Any nodal variable in Sierra/SM can be selected for output in the results file by using a command line in one of the two forms shown above. The only difference between the two forms is the use of ``NODE VARIABLES`` or ``NODAL VARIABLES``. The string ``variable_name`` is the name of the nodal variable to output. The string ``variable_name`` can be either a variable listed in :numref:`output-variables` or a user-defined variable (see :numref:`output-results-user` and :numref:`subroutines-file-variables`). Any nodal variable requested for output is output for all nodes.

An alias can be specified for any of the nodal variables by using the ``AS`` specification. For example, to output the external forces in Sierra/SM, which are defined as ``force_external``, with the alias ``f_ext``, the command line

.. code-block:: sierrainput

   NODE VARIABLES = force_external AS f_ext

would be used. In this example, the external force is a vector quantity. For a vector quantity at a node, suffixes are appended to the variable name (or alias name) to denote each vector component. The results database would have three variable names associated with the external force: ``f_ext_x``, ``f_ext_y``, and ``f_ext_z``. The component separator---an underscore in this example---may be changed using the ``COMPONENT SEPARATOR CHARACTER`` command line (see :numref:`output-results-exodus-component`).

The ``NODE VARIABLES`` command line can be used an arbitrary number of times within a ``RESULTS OUTPUT`` command block. It is also possible to specify more than one nodal variable for output on a command line, as indicated by the ellipsis in the command line format. In the next example, two nodal variables are specified for output. Internal forces are defined as ``force_internal``.

.. code-block:: sierrainput

   NODE VARIABLES = force_external force_internal

Aliases can be optionally specified for each of the variables in a single command line. For example, to output the alias ``f_ext`` for external forces and to output the alias ``f_int`` for internal forces, the command line

.. code-block:: sierrainput

   NODE VARIABLES = force_external AS f_ext
                    force_internal AS f_int

.. _output-nodesetvar:

Output Node Set or Surface Variables
------------------------------------

.. code-block:: sierrainput

   NODESET VARIABLES = <string>variable_name
     [AS <string>dbase_variable_name] ...
     <string>variable_name [AS
     <string>dbase_variable_name]
     | NODESET VARIABLES = <string>variable_name
         [AS <string>dbase_variable_name]
         INCLUDE|ON|EXCLUDE <string list>nodelist_names
         ... <string>variable_name
         [AS <string>dbase_variable_name] INCLUDE|ON|EXCLUDE
         <string list>nodelist_names
   SURFACE VARIABLES = <string>variable_name
     [AS <string>dbase_variable_name] ...
     <string>variable_name [AS
     <string>dbase_variable_name]
     | SURFACE VARIABLES = <string>variable_name
         [AS <string>dbase_variable_name]
         INCLUDE|ON|EXCLUDE <string list>surface_names
         ... <string>variable_name
         [AS <string>dbase_variable_name] INCLUDE|ON|EXCLUDE
         <string list>surface_names

A nodal variable may be defined on a subset of the total set of nodes defining a model or a face variable may be defined on a subset of surfaces. A nodal variable defined only on a subset of nodes is called a node set variable. A face variable defined only on a subset of surfaces is called a surface variable.

The first form of this command line is as follows:

.. code-block:: sierrainput

   NODESET|SURFACE VARIABLES = <string>variable_name
     [AS <string>dbase_variable_name] ...
     <string>variable_name [AS <string>dbase_variable_name]

Here, the string ``variable_name`` is a variable associated with one or more node sets or surfaces. In this form, the variable is output for all node sets or surfaces associated with that variable.

An alias can be specified in the results file for any of the variables by using the ``AS`` option. Suppose, for example, the node set variable ``force_nsetype`` is to be output with the name ``fnsetype`` in the results file. The corresponding command line is:

.. code-block:: sierrainput

  NODESET VARIABLES = force_nsetype AS fnsetype

The ``NODESET|SURFACE VARIABLES`` command line can be used an arbitrary number of times within a ``RESULTS OUTPUT`` command block. It is also possible to specify more than one node set variable for output on a command line, as indicated by the ellipsis in the command line format. In the next example, two node set variables are specified for output. Here, the second node set variable is defined as ``force_nsetype2``.

.. code-block:: sierrainput

   NODESET VARIABLES = force_nsetype force_nsetype2

Aliases can be optionally specified for each of the variables in a single command line. For example, to output the alias ``fnsetype`` for node set variable ``force_nsetype`` and also to output the alias ``fnsetype2`` for node set variable ``force_nsetype2``, the command line

.. code-block:: sierrainput

   NODESET VARIABLES = force_nsetype AS fnsetype
                       force_nsetype2 AS fnsetype2

would be used.

The second form of the command line is as follows:

.. code-block:: sierrainput

   NODESET VARIABLES = <string>variable_name
     [AS <string>dbase_variable_name]
     INCLUDE|ON|EXCLUDE <string list>nodelist_names
     ... <string>variable_name [AS <string>dbase_variable_name]
     INCLUDE|ON|EXCLUDE <string list>nodelist_names
   SURFACE VARIABLES = <string>variable_name
     [AS <string>dbase_variable_name]
     INCLUDE|ON|EXCLUDE <string list>surface_names
     ... <string>variable_name [AS <string>dbase_variable_name]
     INCLUDE|ON|EXCLUDE <string list>surface_names

This form of the ``NODESET|SURFACE VARIABLES`` command line is similar to the first, except that the user can control which node sets are used for output. The user can include a specific list of node sets or surfaces for output by using the ``INCLUDE`` option or the ``ON`` option. (The keyword ``INCLUDE`` is synonymous with the keyword ``ON``.) Alternatively, the user can exclude a specific list of node sets for output by using the ``EXCLUDE`` option.

Suppose that the node set variable ``force_nsetype`` from the above example has been defined for ``nodelist_10``, ``nodelist_11``, ``nodelist_20``, and ``nodelist_21``. If we only want to output the node set variable for node sets ``nodelist_10``, ``nodelist_11``, and ``nodelist_21``,  then we could specify the ``NODESET`` command line as follows:

.. code-block:: sierrainput

   NODESET VARIABLES = force_nsetype AS fnsetype
      INCLUDE nodelist_10, nodelist_11, nodelist_21

(In the above command line, the keyword ``ON`` could be substituted for ``INCLUDE``.)  Alternatively, we could use the command line:

.. code-block:: sierrainput

   NODESET VARIABLES = force_nsetype AS fnsetype
      EXCLUDE nodelist_20

In the above command lines, an alias for a node set can be substituted for a node set identifier. For example, if ``center_case`` is an alias for ``nodelist_10``, then the string ``center_case`` could be substituted for ``nodelist_10`` in the above command lines. Because a node set identifier is a mesh entity, the alias for the node set identifier would be defined via an ``ALIAS`` command line in a ``FINITE ELEMENT MODEL`` command block.

The list of identifiers uses a comma to separate one node set identifier from the next node set identifier.

.. _output-facetvar:

Output Face Variables
---------------------

.. code-block:: sierrainput

   FACE VARIABLES = <string>variable_name
     [AS <string>dbase_variable_name] ...
     <string>variable_name [AS
     <string>dbase_variable_name]
     | FACE VARIABLES = <string>variable_name
         [AS <string>dbase_variable_name]
         INCLUDE|ON|EXCLUDE <string list>surface_names
         ... <string>variable_name
         [AS <string>dbase_variable_name] INCLUDE|ON|EXCLUDE
         <string list>surface_names

A variable may be defined on some set of faces that constitute a surface. A variable defined on a set of faces is called a face variable. The ``FACE VARIABLES`` command line allows the user to specify a face variable for output to the results file. Two forms of the ``FACE VARIABLES`` command line exist and either form will output a face variable. The first form of the command line is as follows:

.. code-block:: sierrainput

   FACE VARIABLES = <string>variable_name
     [AS <string>dbase_variable_name] ...
     <string>variable_name [AS
     <string>dbase_variable_name]

Here, the string ``variable_name`` is a face variable associated with one or more surfaces. In this form, the face variable is output for all surfaces associated with that face variable.

An alias can be specified in the results file for any face variable by using the ``AS`` option. For example, to output a face variable ``pressure_face`` with the name ``pressuref`` in the results file, the command line

.. code-block:: sierrainput

   FACE VARIABLES = pressure_face AS pressuref

would be used. The ``FACE VARIABLES`` command line can be used an arbitrary number of times within a ``RESULTS OUTPUT`` command block. It is also possible to specify more than one face variable for output on a command line, as indicated by the ellipsis in the command line format. In the next example, two face variables are specified for output. Here, the second face variable is defined as ``scalar_face2``:

.. code-block:: sierrainput

   FACE VARIABLES = pressure_face scalar_face2

Aliases can be optionally specified for each of the variables in a single command line. For example, to output the alias ``pressuref`` for face variable ``pressure_face`` and also to output the alias ``scalarf2`` for face variable ``scalar_face2``, the command line

.. code-block:: sierrainput

   FACE VARIABLES = pressure_face AS pressuref
                    scalar_face2 AS scalarf2

The second form of the command line is as follows:

.. code-block:: sierrainput

   FACE VARIABLES = <string>variable_name
     [AS <string>dbase_variable_name]
     INCLUDE|ON|EXCLUDE <string list>surface_names
     ... <string>variable_name
     [AS <string>dbase_variable_name] INCLUDE|ON|EXCLUDE
     <string list>surface_names

This form of the ``FACE VARIABLES`` command line is similar to the first, except that the user can control which surfaces are used for output. The user can include a specific list of surfaces for output by using the ``INCLUDE`` option or the ``ON`` option. (The keyword ``INCLUDE`` is synonymous with the keyword ``ON``.)  Alternatively, the user can exclude a specific list of surfaces for output by using the ``EXCLUDE`` option.

Suppose that the face variable ``pressure_face`` from the above example has been defined for ``surface_10``, ``surface_11``, ``surface_20``, and ``surface_21``. If we only want to output the face variable for ``surface_10``, ``surface_11``, and ``surface_21``,  then we could specify the ``FACE VARIABLES`` command line as follows:

.. code-block:: sierrainput

   FACE VARIABLES = pressure_face AS pressuref
      INCLUDE surface_10, surface_11,
      surface_21

(In the above command line, the keyword ``ON`` could be substituted for ``INCLUDE``.)  Alternatively, we could use the command line:

.. code-block:: sierrainput

   FACE VARIABLES = pressure_face AS pressuref
      EXCLUDE surface_20

In the above command lines, an alias for a surface can be substituted for a surface identifier. For example, if ``center_case`` is an alias for ``surface_10``, then the string ``center_case`` could be substituted for ``surface_10`` in the above command lines. Because a surface identifier is a mesh entity, the alias for the surface identifier would be defined via an ``ALIAS`` command line in a ``FINITE ELEMENT MODEL`` command block.

The list of identifiers uses a comma to separate one surface identifier from the next surface identifier.

.. _output-elevar:

Output Element Variables
------------------------

.. code-block:: sierrainput

   ELEMENT VARIABLES = <string>variable_name
     [AS <string>dbase_variable_name] ...
     <string>variable_name [AS
     <string>dbase_variable_name]
     | ELEMENT VARIABLES = <string>variable_name
         [AS <string>dbase_variable_name]
         INCLUDE|ON|EXCLUDE <string list>block_names
         ... <string>variable_name
         [AS dbase_variable_name] INCLUDE|ON|EXCLUDE
         <string list>block_names

Any element variable in Sierra/SM can be selected for output in the results file by using the ``ELEMENT VARIABLES`` command line. Two forms of the ``ELEMENT VARIABLES`` command line exist and either form will output an element variable. The first form of these command lines are as follows:

.. code-block:: sierrainput

   ELEMENT VARIABLES = <string>variable_name
     [AS <string>dbase_variable_name] ...
     <string>variable_name [AS
     <string>dbase_variable_name]

Here, the string ``variable_name`` is the name of the element variable to output. The string ``variable_name`` can be a variable listed in :numref:`output-variables` or a user-defined variable (see :numref:`output-results-user` and :numref:`subroutines-file-variables`).

In the first form of the ``ELEMENT VARIABLES`` command line, the element variable is output for all element blocks that have the element variable as a defined variable. For example, all the solid elements have ``stress`` as a defined variable. If output of the element variable ``stress`` were requested on a mesh consisting of hexahedral and tetrahedral elements, then ``stress`` would be output for all element blocks consisting of hexahedral and tetrahedral elements.

An alias can be specified for any of the element variables by using the ``AS`` specification. For example, to output the stress in Sierra/SM, which is defined as ``stress``, with the alias ``str``, the command line

.. code-block:: sierrainput

   ELEMENT VARIABLES = stress AS str

would be used. In this example, stress is a symmetric tensor quantity. For a symmetric tensor quantity, suffixes are appended to the variable name (or alias name) to denote each symmetric tensor component. The results database would have six variable names associated with the stress: ``stress_xx``, ``stress_yy``, ``stress_zz``, ``stress_xy``, ``stress_yz``, and ``stress_zx``. The tensor component separator, an underscore in this example, may be changed by using the ``COMPONENT SEPARATOR CHARACTER`` command line (see :numref:`output-results-exodus-component`).

The ``ELEMENT VARIABLES`` command line can be used an arbitrary number of times within a ``RESULTS OUTPUT`` command block. It is also possible to specify more than one element variable for output on a command line, as indicated by the ellipsis in the command line format. In the following example, two element variables are specified for output. Here, the second element variable is defined as ``left_stretch``.

.. code-block:: sierrainput

   ELEMENT VARIABLES = stress left_stretch

Aliases can be optionally specified for each of the variables in a single command line. For example, to output the alias ``str`` for element variable ``stress`` and also to output the alias ``strch`` for face variable ``left_stretch``, the command line

.. code-block:: sierrainput

  ELEMENT VARIABLES = stress AS str
                      left_stretch AS strch

The second form of the command line is as follows:

.. code-block:: sierrainput

   ELEMENT VARIABLES = <string>variable_name
     [AS <string>dbase_variable_name]
     INCLUDE|ON|EXCLUDE <string list>block_names
     ... <string>variable_name
     [AS dbase_variable_name] INCLUDE|ON|EXCLUDE
     <string list>block_names

This form of the ``ELEMENT VARIABLES`` command line is similar to the first, except that the user can control which element blocks are used for output. The user can include a specific list of element blocks for output by using the ``INCLUDE`` option or the ``ON`` option. (The keyword ``INCLUDE`` is synonymous with the keyword ``ON``.) Alternatively, the user can exclude a specific list of element blocks for output by using the ``EXCLUDE`` option.

Suppose the element variable ``stress`` from the above example exists for element blocks ``block_10``, ``block_11``, ``block_20``, and ``block_21``. If we only want to output the element variable for ``block_10``, ``block_11``, and ``block_21``, then we could specify the ``ELEMENT VARIABLES`` command line as follows:

.. code-block:: sierrainput

   ELEMENT VARIABLES = stress AS str
   INCLUDE block_10, block_11,
      block_21

(In the above command line, the keyword ``ON`` could be substituted for ``INCLUDE``.)  Alternatively, we could use the command line:

.. code-block:: sierrainput

   ELEMENT VARIABLES = stress AS str
   EXCLUDE block_20

In the above command lines, an alias for an element block can be substituted for an element block identifier. For example, if ``center_case`` is an alias for ``block_10``, then the string ``center_case`` could be substituted for ``block_10`` in the above command lines. Because an element block identifier is a mesh entity, the alias for the element block identifier would be defined via an ``ALIAS`` command line in a ``FINITE ELEMENT MODEL`` command block. The list of identifiers uses a comma to separate one element block identifier from the next element block identifier.

For multi-integration point elements, quantities from the integration points are appended with a numerical index indicating the integration point. A suffix ranging from :math:`1` to the number of integration points is attached to the quantity to indicate the corresponding integration point. The suffix is padded with leading zeros. If the number of integration points is less than 10, the suffix has the form ``_i``, where ``i`` ranges from ``1`` to the number of integration points. If the number of integration points is greater than or equal to 10 and less than 100, the sequence of suffixes takes the form ``_01``, ``_02``, ``_03``, and so forth. Finally, if the number of integration points is greater than or equal to 100, the sequence of suffixes takes the form ``_001``, ``_002``, ``_003``, and so forth. As an example, if the von Mises stress is requested for a shell element with 15 integration points, then the quantities ``von_mises_01``, ``von_mises_02``,... , ``von_mises_15`` are output for the shell element.

In the above discussion concerning the format for output at multiple integration points, the underscore character preceding the integration point number can be replaced by another delimiter or the underscore character can be eliminated by use of the ``COMPONENT SEPARATOR CHARACTER`` command line (see :numref:`output-results-exodus-component`).

Shell tensor quantities ``transform_shell_stress``, ``transform_shell_strain`` and ``transform_shell_rate_of_deformation`` may be transformed to a user specified shell local co-rotational coordinate system (an in-plane coordinate system that rotates with the shell element) for output using the ``ORIENTATION`` shell section command. If no orientation is specified, these in-plane stresses and strains are output in the default orientation. See :numref:`elements-sections-shell` for more details.

.. _output-outputsubsetting:

Subsetting of Output Mesh
-------------------------

A specified subset of the entities (element blocks, nodesets, surfaces) in the mesh can be output to the results database using the ``INCLUDE`` or ``EXCLUDE`` commands. The syntax is:

.. code-block:: sierrainput

   INCLUDE = <string>list_of_included_entities
   EXCLUDE = <string>list_of_excluded_entities

Either command can appear multiple times within the results output block, but a specific entity cannot be specified in both. If the ``INCLUDE`` command is specified, the results database will only contain the listed entities of that type; if the ``EXCLUDE`` command is specified, the results database will contain all entities of the type listed except for the listed entities. If the model has surfaces or nodesets, only the portion of the surfaces or nodesets on the selected element blocks will be output.

.. _output-outputmesh:

Output Mesh Selection
---------------------

.. code-block:: sierrainput

   OUTPUT MESH = REFINED|EXPOSED SURFACE (REFINED)

The ``OUTPUT MESH`` command provides a way to reduce the amount of data written to the results database. There are two options that can be selected:

- ``REFINED`` Outputs the full 3D model in the current mesh configuration.

- ``EXPOSED SURFACE`` Only output the element faces that make up the "skin" of the finite element model; no internal nodes or elements will be written to the results database. The element results variables will be applied to the skin faces. If the mesh is visualized without any cutting planes, the display should look the same as if the original full mesh were visualized; however, the amount of data written to the output file can be much less than is needed if the full mesh were output.

.. warning::
   OUTPUT MESH = EXPOSED SURFACE does not currently work with element variables.

.. _output-results-exodus-component:

Component Separator Character
-----------------------------

.. code-block:: sierrainput

   COMPONENT SEPARATOR CHARACTER = <string>character|NONE

The component separator character is used to separate an output-variable base name from any suffixes. For example, the variable ``stress`` can have the suffixes ``xx``, ``yy``, etc. By default, the base name is separated from the suffixes with an underscore character so that we have ``stress_xx``, ``stress_yy``, etc. in the results output file.

The underscore can be replaced as the default separator by using the above command line. For example, to use a period (``.``) as the separator, the command line

.. code-block:: sierrainput

   COMPONENT SEPARATOR CHARACTER = .

would be used. For the ``stress`` output example, stress components would then appear in the results output file as ``stress.xx``, ``stress.yy``, etc. For shell element blocks, an integration point suffix preceded, by default, with an underscore is also present; the above command line also resets this separator character to period (``.``). In the ``stress`` output example, in this case the results file would contain ``stress.xx.01``, ``stress.xx.02``, etc., for the shell elements. The separator can be eliminated with an empty string or ``NONE``.

.. _output-glovar:

Output Global Variables
-----------------------

.. code-block:: sierrainput

   GLOBAL VARIABLES = <string>variable_name
     [AS <string>dbase_variable_name] ...
     <string>variable_name [AS
     <string>dbase_variable_name]

Any global variable in Sierra/SM can be selected for output in the results file by using the ``GLOBAL VARIABLES`` command line. The string ``variable_name`` is the name of the global variable. The string ``variable_name`` can be either a variable listed in :numref:`output-variables` or a user-defined variable (see :numref:`output-results-user` and :numref:`subroutines-file-variables`).

Kinetic, external, hourglass, internal energies and momentum can be requested as the sum over the entire mesh. (See the Sierra/SM Theory Manual [:footcite:`sierraSMTheoryManual`] for details on momentum and energy balance. Internal energy includes both elastic and dissipated energy and contact energy is included in the external energy. Significant error in the energy balance (see :numref:`explicit-procedure-stepint`) often indicates the problem is under-resolved.) For example, the total kinetic energy can be output as:

.. code-block:: sierrainput

   GLOBAL VARIABLES = kinetic_energy as ke

Block internal, strain, and hourglass energies can be output on a block-by-block basis by using a user output block such as the following:

.. code-block:: sierrainput

   BEGIN USER OUTPUT
     BLOCK = BLOCK_100
     COMPUTE GLOBAL BLOCK_100_IE AS SUM OF ELEMENT INTERNAL_ENERGY
     COMPUTE GLOBAL BLOCK_100_SE AS SUM OF ELEMENT STRAIN_ENERGY
     COMPUTE GLOBAL BLOCK_100_HGE AS SUM OF ELEMENT HOURGLASS_ENERGY
   END

The sum of the block strain energy and the block hourglass block energy should equal the block internal energy.

With the ``AS`` keyword, the variable and an alias for this variable may be optionally specified in the results file. For example, to output the time steps in Sierra/SM (``timestep``) with the alias ``tstep``, the command line

.. code-block:: sierrainput

   GLOBAL VARIABLES = timestep AS tstep

would be used. The ``GLOBAL VARIABLES`` command line can be used an arbitrary number of times within a ``RESULTS OUTPUT`` command block. It is also possible to specify more than one global variable for output on a command line. If output of the CPU time (``cpu_time``) is also desired for output with the alias ``cpu``, the command line

.. code-block:: sierrainput

   GLOBAL VARIABLES = timestep as tstep cpu_time as cpu

should be used.

.. _output-results-exodus-timesteps:

Specifying Time Steps for Output
--------------------------------

.. parsed-literal::

   START TIME = <real>output_start_time
   TERMINATION TIME = <real>output_termination_time
   AT TIME <real>time_begin INCREMENT = <real>time_increment_dt
   AT STEP <integer>step_begin INCREMENT = <integer>step_increment
   ADDITIONAL TIMES = <real>output_time1 <real>output_time2 ...
   ADDITIONAL STEPS = <integer>output_step1 <integer>output_step2 ...
   TIMESTEP ADJUSTMENT INTERVAL = <integer>steps |explicit_mini|

Several options are available to define output; output steps will be included in a results, history, or heartbeat output file. Note, these commands control only what time steps will be output, not what time steps will be computed. Thus requesting output at some time :math:`N` will trigger an output of the next computed time step that is equal to or greater than time :math:`N`. The analysis time stepping setup controls what time steps are computed, see :numref:`explicit-procedure` and :numref:`implicit-timestep`.

Using the ``START TIME`` command line, results are output to file beginning at time ``output_start_time``. This command is optional, but if present, no results will be written before the ``output_start_time``. If other commands set times for results output (e.g., ``AT TIME``, ``ADDITIONAL TIMES``) that are less than ``output_start_time``, those times will be ignored, and results will not be written at those times.

If the ``TERMINATION TIME`` command is used, results will not be written to the results file after time ``output_termination_time``. If other commands set times for results such (``AT TIME``, ``ADDITIONAL TIMES``) that are greater than ``termination_time_value``, those times will be ignored, and results will not be written at those times.

The ``AT TIME`` command will trigger output starting at the time specified by ``time_begin`` as long as this time is greater than ``output_start_time`` specified in a ``START TIME`` command, and then at every subsequent time increment ``time_increment_dt`` thereafter. Output will also occur at the end of the analysis even if it does not fall exactly at one of the specified intervals.

The ``AT STEP`` command will trigger output starting at the step specified by ``step_begin`` and then at every subsequent step increment ``step_increment`` thereafter. Output will also occur at the end of the analysis even if it does not fall exactly at a specified interval.

If both the ``AT TIME`` and the ``AT STEP`` commands are used time steps that match either condition will be output. For example the following would output time steps ``0.0001``, ``0.0002``, ``0.0003``, etc., as well as every hundredth step.

.. code-block:: sierrainput

   at time 0.0, increment = 0.0001
   at step 0, increment = 100

If multiple ``AT TIME`` or ``AT STEP`` commands are used the commands define different output frequencies at different time intervals. For example:

.. code-block:: sierrainput

   at time 0.00, increment = 0.25
   at time 1.00, increment = 0.01
   at time 1.05, increment = 0.25

From time ``0.00`` to ``1.00`` the steps will output at time interval ``0.25``, at time ``1.00`` the output interval will switch to ``0.01`` and then the output interval witch switch back to ``0.25`` at time ``1.05``. Specifically this will output the following time steps ``0.00, 0.25, 0.50, 0.75, 1.00, 1.01, 1.02, 1.03, 1.04, 1.05, 1.30, 1.55, etc.``. Use of multiple ``AT TIME`` or ``AT STEP`` commands is often used to obtain high frequency of output at some critical analysis time while still limiting the overall size of the results file.

The ``ADDITIONAL TIMES`` command line can be used to specify a number of additional output times. If ``output_start_time`` is specified in a ``START TIME`` command, then no additional times that are less than ``output_start_time`` will output. Output will also occur at the end of the analysis even if it does not fall exactly at a specified interval.

The ``ADDITIONAL STEPS`` command line can be used to specify output at a number of other analysis steps. If ``output_start_time`` is specified in a ``START TIME`` command, then no additional steps at times less than ``output_start_time`` will output. Output will also occur at the end of the analysis even if it does not fall exactly at a specified interval.

|explicit| The ``TIMESTEP ADJUSTMENT INTERVAL`` command line specifies that the output will be at exactly the times specified. To hit the output times exactly in an explicit, transient dynamics code, it is necessary to adjust the time step as the time approaches an output time. The integer value ``steps`` in the ``TIMESTEP ADJUSTMENT INTERVAL`` command line specifies the number of time steps to look ahead to adjust the time step. This command is only functional in explicit analysis. If this command line does not appear, results are output at times closest to the specified output times.

**Examples**

The following examples demonstrate how time step output works for many cases. For this example assume the analysis time stepping is setup to compute the following steps:

.. csv-table::
   :align: center
   :delim: &
   :widths: auto

   step & 1 & 2 & 3 & 4 & 5 & 6 & 7 & 8 & 9 & 10 & 11
   time & 0.0 & 0.5 & 1.0 & 1.5 & 2.0 & 2.5 & 3.0 & 3.5 & 4.0 & 4.5 & 5.0

-
  .. code-block:: sierrainput

     at step 0, increment = 1
  
  This will output all 11 computed time steps.

-
  .. code-block:: sierrainput

     at step 1, increment = 4
     additional steps = 6 7
  
  This will output every third time step, steps 6 and 7, and the final time step, i.e., steps 1, 5, 6, 7, 9, and 11.

-
  .. code-block:: sierrainput

     additional times 1.6
  
  This will output at the next computed time :math:`t` after the specified time :math:`t_o = 1.6`, so output will be written only at step 5, at time :math:`t = 2.0 > t_o`.

-
  .. code-block:: sierrainput

     at time 0.0, increment = 1.3
  
  This will output every 1.3 seconds of analysis times, i.e., times 0.0, 1.3, 2.6, 3.9, and 5.2. For a specified output time :math:`t_o` not coincident with actual simulation time steps :math:`\{t_s\}`, the next simulation time step :math:`t \in \{t_s\},\, t \ge t_o` will be output. The actual output steps will then be as follows:

.. csv-table::
   :align: center
   :delim: &
   :widths: auto

   step & 1 & 4 & 7 & 9
   time & 0.0 & 1.5 & 3.0 & 4.0

-
  .. code-block:: sierrainput

     at step 0, increment = 1
     start time = 2.0
     end time = 4.0
  
  This will output at every step between the specified start and end times, i.e., at steps 5, 6, 7, 8, and 9.

.. _output-results-exodus-synchronize:

Synchronize Output
------------------

.. code-block:: sierrainput

   SYNCHRONIZE OUTPUT

In an analysis with multiple regions, it is sometimes desirable to synchronize the output of results data between the regions. This can be done by adding the ``SYNCHRONIZE OUTPUT`` command line to the results output block. If a results block has this set, then it will write output whenever a previous region writes output. The ordering of regions is based on the order in the input file, algorithmic considerations, or by solution control specifications.

Although the ``USE OUTPUT SCHEDULER`` command line can also synchronize output between regions, the ``SYNCHRONIZE OUTPUT`` command line will synchronize the output with regions where the output frequency is not under the direct control of the Sierra IO system. Examples of this are typically coupled applications where one or more of the codes are not Sierra-based applications such as Alegra and CTH. A results block with ``SYNCHRONIZE OUTPUT`` specified will also synchronize its output with the output of the external code.

The ``SYNCHRONIZE OUTPUT`` command can be used with other output scheduling commands such as time-based or step-based output specifications.

.. _output-results-exodus-scheduler:

Use Output Scheduler
--------------------

.. code-block:: sierrainput

   USE OUTPUT SCHEDULER <string>scheduler_name

In an analysis with multiple regions, it can be difficult to synchronize output such as results files. To help synchronize output for analyses with multiple regions, an ``OUTPUT SCHEDULER`` command block may be specified at the SIERRA scope. The scheduler can then be referenced in the ``RESULTS OUTPUT`` command block via the ``USE OUTPUT SCHEDULER`` command line. The string ``scheduler_name`` must match a name used in an ``OUTPUT SCHEDULER`` command block. See :numref:`output-scheduler` for a description of using this command block and the ``USE OUTPUT SCHEDULER`` command line.

.. _output-rowriteres:

Write Results If System Error Encountered
-----------------------------------------

.. code-block:: sierrainput

   OUTPUT ON SIGNAL = <string>SIGALRM|SIGFPE|SIGHUP|SIGINT|
     SIGPIPE|SIGQUIT|SIGTERM|SIGUSR1|SIGUSR2|SIGABRT|
     SIGKILL|SIGILL|SIGSEGV

The ``OUTPUT ON SIGNAL`` command line is used to initiate the writing of a results file when the system encounters a system error. Only one error type in the list of error types should be entered for this command line. These system errors cause the code to terminate before the code can add any current results output (results output past the last results output time step) to the results output file. If the code encounters the specified error type during execution, a results file will be written before execution is terminated. This command line can also be used to force the writing of a results file at some point during execution of the code. Suppose the command line

.. code-block:: sierrainput

   OUTPUT ON SIGNAL = SIGUSR2

is included in the input file. While the code is running, a user can execute (from the keyboard) the system command line

.. code-block:: sh

   kill -s SIGUSR2 *pid*

to terminate execution and force the writing of a results file. In the above system command line, *pid* is the process identifier, an integer. The ``OUTPUT ON SIGNAL`` command line is primarily a debugging tool for code developers.

.. _output-roautooutput:

Automatically Add User Output Variables To Results Output
---------------------------------------------------------

.. code-block:: sierrainput

   AUTO OUTPUT <string>NODAL|ELEMENT|GLOBAL|ALL USER DEFINED VARIABLES 
     [IN <string>user_output_block_name_list]

The ``AUTO OUTPUT`` command line is used to automatically add all of the user  output variables defined in a region. The number of variables can be limited by selecting the entity type that is needed with ``NODAL|ELEMENT|GLOBAL|ALL``. Another  way to limit the number of variables added is the option command  ``IN <string>user_output_block_name_list`` this will only add the selected entities  type that is in the defined user output block list.

.. raw::
  html

  <hr>

.. footbibliography::
