.. _output-history:

**************
History Output
**************

.. parsed-literal::

   BEGIN HISTORY OUTPUT <string>history_name
     #
     # Database Commands
     DATABASE NAME = <string>history_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>propValue
     #
     # for global variables
     GLOBAL <string>variable_name
       [AS <string>history_variable_name]
     #
     # for mesh entity - node, edge, face,
     # element - variables
     NODE|NODAL|EDGE|FACE|ELEMENT <string>variable_name
       AT NODE|NODAL|EDGE|FACE|ELEMENT <integer>entity_id
       AS <string>history_variable_name
     # for edge or face variables
     EDGE|FACE <string>variable_name
       AT EDGE|FACE <integer>entity_id.local_face
       AS <string>history_variable_name
     #
     # for nearest point output of mesh entity - node,
     # edge, face, element - variables
     NODE|NODAL|EDGE|FACE|ELEMENT <string>variable_name
       NEAREST LOCATION <real>global_x,
         <real>global_y, <real>global_z
       AS <string>history_variable_name
     START TIME = <real>output_start_time
     TIMESTEP ADJUSTMENT INTERVAL = <integer>steps |explicit_mini|
     AT TIME <real>time_begin INCREMENT =
       <real>time_increment_dt
     ADDITIONAL TIMES = <real>output_time1
       <real>output_time2 ...
     AT STEP <integer>step_begin INCREMENT =
       <integer>step_increment
     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>GLOBAL|ALL USER DEFINED VARIABLES
       [IN <string>user_output_block_name_list]
   END [HISTORY OUTPUT <string>history_name]

A history file gives nodal variable results (displacements, forces, etc.) for specific nodes, edge variable results for specific edges, face variable results for specific faces, element results (stress, strain, etc.) for specific elements, and global results at specified times. A history file, the results to be included in this file, and the frequency at which results are written may be specified by a ``HISTORY OUTPUT`` command block. The command block appears inside the region scope. Typically, node, element, and occasionally face variables may be included.

More than one history file can be specified for an analysis. For each history file will correspond to one ``HISTORY OUTPUT`` command block in the input file. The command block for a history file description begins with:

.. code-block:: sierrainput

   BEGIN HISTORY OUTPUT <string>history_name and is terminated with:

.. code-block:: sierrainput

   END [HISTORY OUTPUT <string>history_name]

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

See :numref:`output-commands` for details on the general database commands such as ``DATABASE NAME``, ``DATABASE TYPE``, ``OVERWRITE``, etc.

The other command lines that appear in the ``HISTORY OUTPUT`` command block determine the type and frequency of output information. Descriptions of these command lines follow in :numref:`output-var` through :numref:`output-writehis`. The command lines for controlling the frequency of history output (in :numref:`output-var` through :numref:`output-writehis`) are the same as those for controlling the frequency of results output. These frequency-related command lines are repeated here for convenience.

.. _output-var:

Output Variables
================

The ``GLOBAL``, ``NODE`` (or ``NODAL``), ``EDGE``, ``FACE``, or ``ELEMENT`` command line is used to select variables for output in the history file. One of several types of variables can be selected for output. The form of the command line varies depending on the variable type selected for output.

.. _output-globoutvar:

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

.. code-block:: sierrainput

   GLOBAL <string>variable_name
     [AS <string>history_variable_name]
   
This form of the command line lets the user select any global variable for output in the history file. The variable is selected with the string ``variable_name``. The string ``variable_name`` is the name of the global variable and 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`).

A name, ``history_variable_name``, can also be specified for the selected entity following the ``AS`` keyword. For example, suppose it is desired to output the CPU time (``cpu_time``) as ``cpu`` in the history file. The command line to accomplish this would be:

.. code-block:: sierrainput

   GLOBAL cpu_time AS cpu

The specification of an alias is optional for output of a global variable.

.. _output-meshenoutvar:

Mesh Entity Output Variables
----------------------------

.. code-block:: sierrainput

   NODE|NODAL|EDGE|FACE|ELEMENT <string>variable_name
     AT NODE|NODAL|EDGE|FACE|ELEMENT <integer>entity_id
     AS <string>history_variable_name
 
This form of the command line allows the user to select any nodal, edge, face, or element variable for a specific mesh entity for output in the history file. For example, this form of the command line will pick the displacement at a specific node and output the displacement to the history file using a specified alias.

For this form of the command line, the mesh entity type is set to ``NODE`` (or ``NODAL``), ``EDGE``, ``FACE``, or ``ELEMENT`` depending on the variable (set by ``variable_name``) to be output. If the mesh entity type is set to ``NODE`` (or ``NODAL``), ``EDGE``, or ``FACE``, 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`). If the mesh entity type is set to ``ELEMENT``, 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`).

Selection of a mesh entity follows the ``AT`` keyword. A mesh entity type (``NODE`` [or ``NODAL``], ``EDGE``, ``FACE``, or ``ELEMENT``) must be specified, followed by the integer identifier, ``entity_id``, for the mesh entity. A name, ``history_variable_name``, for the selected entity must also be specified following the ``AS`` keyword. For example, output of accelerations at node 88 would be specified using the command line:

.. code-block:: sierrainput

   NODE ACCELERATION AT NODE 88 AS accel_88

where ``accel_88`` is the name used for this history variable in the history file.

For face and edge variables, an additional method of specifying the face or edge entity is provided. This method selects the face or edge by specifying the element that the face or edge is a member of and the local face or edge number on that element. To use this method, the element id and the face ordinal are specified as ``id.ordinal``. The numbering of an elements faces and edges is specified in the ExodusII users manual [:footcite:`int:ref:scho`]. Note that the selected face or edge must exist in the mesh database as a face or edge on a sideset, or the face or edge must be created internally by the application.

As an example, the command line to obtain the pressure for the third face of element 42 for the history file would be:

.. code-block:: sierrainput

   FACE PRESSURE AT FACE 42.3 AS PRES_42.3

Either the keyword ``NODE`` or ``NODAL`` can be used for nodal quantities.

As an example, the command line to obtain the von Mises stress for element 1024 for the history file would be:

.. code-block:: sierrainput

   ELEMENT VON_MISES AT ELEMENT 1024 AS GM_1024

Material state variables may be output in the same way. If an element has the state variable 'EQPS' then the value of 'EQPS' could be obtained on the element with a statement of the form:

.. code-block:: sierrainput

   ELEMENT EQPS AT ELEMENT 1024 AS eqps_1024

Additionally, the at element command supports the standard variable component syntax. For example:

.. code-block:: sierrainput

   ELEMENT STRESS(XX) AT ELEMENT 1024 AS S_XX_1024

where ``S_XX_1024`` is the name that will be used for this history variable in the history file.

.. _output-nearptoutvar:

Nearest Point Output Variables
------------------------------

.. code-block:: sierrainput

   NODE|NODAL|EDGE|FACE|ELEMENT <string>variable_name
     NEAREST LOCATION <real>global_x,
       real<global_y>, real<global_z>
     AS <string>history_variable_name

This form of the command line allows the user to select any nodal, edge, face, or element variable for output in the history file using a nearest point criterion. The command line described in this subsection is an alternative to the command line described in the preceding section, :numref:`output-meshenoutvar`, for obtaining history output. The command line in this section or the command line in :numref:`output-meshenoutvar` produces history files with variable information. The difference between the two is how the variable information is selected.

For the above form of the command line, the mesh entity type is set to ``NODE`` (or ``NODAL``), ``EDGE``, ``FACE``, or ``ELEMENT`` depending on the variable (set by ``variable_name``) to be output. If the mesh entity type is set to ``NODE`` (or ``NODAL``), ``EDGE``, or ``FACE``, 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`). If the mesh entity type is set to ``ELEMENT``, 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`).

The specific mesh entity used for output is determined by global coordinates specified by the ``NEAREST LOCATION`` keyword and its associated input parameters---``global_x``, ``global_y``, ``global_z``. The specific mesh entity chosen for output is as follows:

- If the mesh entity has been set to ``NODE`` (or ``NODAL``), the node in the mesh selected for output is the node whose initial position is nearest the input global X, Y, and Z coordinates specified with the parameters ``global_x``, ``global_y``, and ``global_z``.

- If the mesh entity has been set to ``EDGE``, the edge in the mesh selected for output is the edge with a center point (the average location of the two end points of the edge) whose initial position is nearest the input global X, Y, and Z coordinates specified with the parameters ``global_x``, ``global_y``, and ``global_z``.

- If the mesh entity has been set to ``FACE``, the face in the mesh selected for output is the face with a centroid whose initial position is nearest the input global X, Y, and Z coordinates specified with the parameters ``global_x``, ``global_y``, and ``global_z``.

- If the mesh entity has been set to ``ELEMENT``, the element in the mesh selected for output is the element with a centroid whose initial position is nearest the input global X, Y, and Z coordinates specified with the parameters ``global_x``, ``global_y``, and ``global_z``.

In all the above cases, the original model coordinates are used when selecting the nearest entity, not the current coordinates.

A name, ``history_variable_name``, must be specified for the selected entity following the ``AS`` keyword. As an example, to output the accelerations at a node closest to the point with global coordinates (1012.0, 54.86, 103.3141), the command line

.. code-block:: sierrainput

   NODE ACCELERATION
        NEAREST LOCATION 1012.0, 54.86, 103.3141 AS accel_near

would be used, where ``accel_near`` is the name used for this history variable in the history file. Either the keyword ``NODE`` or ``NODAL`` can be used for nodal quantities.

.. _output-hdat:

Outputting History Data on a Node Set
=====================================

It is commonly desired to output history data on a single-node node set. If a mesh file is slightly modified, the node and element numbers will completely change. The node associated with a node set, however, remains the same, i.e., the node in the node set retains the same initial geometric location with the same connectivity to other elements, even when its node number changes. Therefore, we might want to specify the history output for a node set with a single node rather than with the global identifier for a node. This can easily be accomplished, as follows:

.. code-block:: sierrainput

   begin user output
     node set = nodelist_1
     compute global disp_ns_1 as average of nodal displacement
   end
   
   begin history output
     global disp_ns_1
   end

If ``nodelist_1`` contains only a single node, the history output variable ``disp_ns_1`` will contain the displacement for the single node in the node set. If ``nodelist_1`` contains multiple nodes, the average displacement of the nodes will be output.

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

The same output step control commands available for results output are also available for history output. See :numref:`output-results-exodus-timesteps`.

.. _output-hissynchronize:

Synchronize Output
==================

.. code-block:: sierrainput

   SYNCHRONIZE OUTPUT

The ``SYNCHRONIZE OUTPUT`` command can be used in the same manner it is used in the exodus output command block. See :numref:`output-results-exodus-synchronize` for more details about this command.

.. _output-hisuseoutput:

Use Output Scheduler
====================

.. code-block:: sierrainput

   USE OUTPUT SCHEDULER <string>scheduler_name

The ``USE OUTPUT SCHEDULER`` command can be used in the same manner it is used in the exodus output command block. See :numref:`output-results-exodus-scheduler` for more details about this command.

.. _output-writehis:

Write History 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 history file when the system encounters a type of 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 history output (history output past the last history output time step) to the history file. If the code encounters the specified error type during execution, a history file will be written before execution is terminated. This command line can also be used to force the writing of a history 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-hoautooutput:

Automatically Add User Output Variables To History Output
=========================================================

.. code-block:: sierrainput

   AUTO OUTPUT <string>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 amount of global variables can be limited by using the optional command ``IN <string>user_output_block_name_list`` which will only add the global variables in the defined user output block list. 

.. warning::

   While ``AUTO OUTPUT`` does have the option for ``NODAL|ELEMENT|ALL`` currently  it will only output GLOBAL variables. If ``NODAL|ELEMENT`` are used a warning will be thrown in the logfile and nothing will be added.

.. raw::
  html

  <hr>

.. footbibliography::
