9.7. History Output

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    
  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:

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

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 Section 9.2 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 Section 9.7.1 through Section 9.7.5. The command lines for controlling the frequency of history output (in Section 9.7.1 through Section 9.7.5) are the same as those for controlling the frequency of results output. These frequency-related command lines are repeated here for convenience.

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

9.7.1.1. Global Output Variables

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 Section 9.13 or a user-defined variable (see Section 9.4 and Section 10.1).

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:

GLOBAL cpu_time AS cpu

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

9.7.1.2. Mesh Entity Output Variables

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 Section 9.13 or a user-defined variable (see Section 9.4 and Section 10.1). If the mesh entity type is set to ELEMENT, the string variable_name can be a variable listed in Section 9.13 or a user-defined variable (see Section 9.4 and Section 10.1).

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:

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 [[1]]. 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:

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:

ELEMENT VON_MISES AT ELEMENT 1024 AS VM_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:

ELEMENT EQPS AT ELEMENT 1024 AS eqps_1024

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

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.

9.7.1.3. Nearest Point Output 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

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, Section 9.7.1.2, for obtaining history output. The command line in this section or the command line in Section 9.7.1.2 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 Section 9.13 or a user-defined variable (see Section 9.4 and Section 10.1). If the mesh entity type is set to ELEMENT, the string variable_name can be a variable listed in Section 9.13 or a user-defined variable (see Section 9.4 and Section 10.1).

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

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.

9.7.2. 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:

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.

9.7.2.1. Specifying Time Steps for Output

The same output step control commands available for results output are also available for history output. See Section 9.3.1.9.

9.7.3. Synchronize Output

SYNCHRONIZE OUTPUT

The SYNCHRONIZE OUTPUT command can be used in the same manner it is used in the exodus output command block. See Section 9.3.1.10 for more details about this command.

9.7.4. Use Output Scheduler

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 Section 9.3.1.11 for more details about this command.

9.7.5. Write History If System Error Encountered

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

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

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.

9.7.6. Automatically Add User Output Variables To History Output

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.

---

[1]

L.A. Schoof and V.R. Yarberry. EXODUS II: a finite element data model. Technical Report SAND92-2137, Sandia National Laboratories, Albuquerque, NM, September 1994. URL: http://infoserve.sandia.gov/sand_doc/1992/922137.pdf.