9.8. Heartbeat Output

BEGIN HEARTBEAT OUTPUT <string>heartbeat_name
  # Can also use predefined streams "cout", "stdout",
  # "cerr", "clog", "log", "output", or "outputP0"
  STREAM NAME = <string>heartbeat_file_name
  APPEND = ON|OFF (OFF)
  #
  # Specify whether heartbeat file will be in spyhis (cth)
  # format, or default format
  FORMAT = SPYHIS|ORIGINAL|CSV(CSV)
  #
  # for global variables
  GLOBAL <string>variable_name
    [AS <string>heartbeat_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>heartbeat_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>heartbeat_variable_name
  # for edge or face variables
  EDGE|FACE <string>variable_name
    AT EDGE|FACE <integer>entity_id.local_face
    AS <string>heartbeat_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
  PRECISION = <integer>precision
  LABELS = <string>OFF|ON
  LEGEND = <string>OFF|ON
  TIMESTAMP FORMAT <string>timestamp_format
  MONITOR = <string>RESULTS|RESTART|HISTORY
  AUTO OUTPUT <string>GLOBAL|ALL USER DEFINED VARIABLES
    [IN <string>user_output_block_name_list]
END [HEARTBEAT OUTPUT <string>heartbeat_name]

The heartbeat output is text output file that 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.

Known Issue

user-defined variables (see Section 10.2.4) are not currently supported with heartbeat output.

The output is written as text instead of the binary history output. A heartbeat file, the results to be included in this file, the formatting of the output, and the frequency at which results are written may be specified using a HEARTBEAT OUTPUT command block. The command block appears inside the region scope. Heartbeat output may typically involve global, node, and element variables, and, on some occasions, face variables.

More than one heartbeat file can be specified for an analysis. For each heartbeat file, there will be one HEARTBEAT OUTPUT command block. The command block for a heartbeat file description begins with

BEGIN HEARTBEAT OUTPUT <string>heartbeat_name

and is terminated with

END [HEARTBEAT OUTPUT <string>heartbeat_name]

where heartbeat_name is a user-selected name for the command block. Nested within the HEARTBEAT OUTPUT command block are a set of command lines, as shown in the block summary given above. The first command line listed (STREAM NAME) gives pertinent information about the heartbeat file. The command line

STREAM NAME = <string>heartbeat_file_name

gives the name of the heartbeat file with the string heartbeat_file_name. A file that already exists is overwritten. If the heartbeat file is to appear in the current directory and is named job.h, this command line would appear as

STREAM NAME = job.h

If the heartbeat file is to be created in some other directory, the command line would have to show the absolute path to that directory. If the directory does not exist yet, all necessary directories are automatically created.

In addition to specifying a specific file name, there are several predefined streams that can be specified. The predefined streams are:

cout or stdout specifies standard output;
cerr, stderr, clog, or log specifies standard error;
output or outputP0 specifies Sierra’s standard output which is redirected to the file specified by the -o option on the command line.

Two meta-characters can appear in the name of the heartbeat file. If the %P character is found in the name, it will be replaced with the number processors being used for the run. For example, if, in a given analysis on 1024 processors, the name heartbeat-%P/job.h is used, then the name would be expanded to heartbeat-1024/job.h. The other recognized meta-character is %B replaced with the base name of the input file containing the input commands. For example, if the commands are in the file my_analysis_run.i and the heartbeat stream name is specified as %B.h, then the heartbeat data would be written to the file my_analysis_run.h. If the stream name command line is omitted, the default file name will be %B.hrt which is the base name of the input file with the extension .hrt

The other command lines that appear in the HEARTBEAT OUTPUT command block determine the type, frequency, and format of output information. Descriptions of these command lines follow in Section 9.8.1 through Section 9.8.8. The command lines for controlling the frequency of heartbeat output (in Section 9.3.1.9) are the same as those for controlling the frequency of results and history output. The APPEND command can be used to cause heartbeat information output by the current run to append to an existing file name rather than overwrite the existing file.

9.8.1. Output Variables

The GLOBAL, NODE (or NODAL), EDGE, FACE, or ELEMENT command line is used to select variables for output in the heartbeat 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.8.1.1. Global Output Variables

GLOBAL <string>variable_name
  [AS <string>heartbeat_variable_name]

This form of the command allows the user to select any global variable for output in the heartbeat 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.2.4). The variable_name can also specify time, timestep, or step to output the current simulation time, time step, or execution step, respectively.

A name, heartbeat_variable_name, for the selected entity can also be optionally specified following the AS keyword. For example, the CPU time (cpu_time) could be output as cpu in the heartbeat file using the command:

GLOBAL cpu_time AS cpu

9.8.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>heartbeat_variable_name

This form of the command allows the user to select any nodal, edge, face, or element variable for a specific mesh entity for output in the heartbeat file. For example, this command line will pick the displacement at a specific node and output the displacement to the heartbeat file using a chosen alias.

For this form of the command, 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.2.4). 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.2.4).

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

NODE ACCELERATION AT NODE 88 AS accel_88

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

For face and edge variables, an additional method of specifying the specific 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 Exodus II 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 heartbeat 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 heartbeat file would be:

ELEMENT VON_MISES AT ELEMENT 1024 AS vm_1024

where vm_1024 is the name used for this heartbeat variable in the heartbeat file.

9.8.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>heartbeat_variable_name

This form of the command allows the user to select any nodal, edge, face, or element variable for output in the heartbeat 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.8.1.2, for obtaining heartbeat output. The command line in this section or the command line in Section 9.8.1.2 produces heartbeat files with variable information. The difference in these two command lines (Section 9.8.1.3 and Section 9.8.1.2) is how the variable information is selected.

For the above form of the command, 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.2.4). 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.2.4).

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, heartbeat_variable_name, for the selected entity may be specified following the AS keyword. As an example, accelerations at a node closest to the point with global coordinates (1012.0, 54.86, 103.3141) may be output with the command line:

NODE ACCELERATION
    NEAREST LOCATION 1012.0, 54.86, 103.3141 AS accel_near

where accel_near is the name used for this heartbeat variable in the heartbeat file.

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

9.8.2. Outputting Heartbeat Data on a Node Set

It is commonly desired to output heartbeat 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 heartbeat 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 heartbeat output
  global disp_ns_1
end

If nodelist_1 contains only a single node, the heartbeat 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.8.3. Specifying Time Steps for Output

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

9.8.4. 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.8.5. 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.8.6. Write Heartbeat On Signal

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 heartbeat file when the system encounters the specified signal. The signal can either occur as the result of a system error, or the user can explicitly send the specified signal to the application (See the system documentation man pages for “signal” or “kill” for more information). Only one signal type in the list of signal types should be entered for this command line. These signals cause the code to terminate before the code can add any current heartbeat output (heartbeat output past the last heartbeat output time step) to the heartbeat file. If the code encounters the specified error type during execution, a heartbeat file will be written before execution is terminated. This command line can also be used to force the writing of a heartbeat 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 force the writing of a results file. In the above system command line, pid is the process identifier, which is an integer. The OUTPUT ON SIGNAL command line is primarily a debugging tool for code developers.

9.8.7. Heartbeat Output Formatting Commands

There are several command lines for the heartbeat section that modify the formatting of the heartbeat text output. The default output for the heartbeat data consists of a line beginning with a timestamp showing the current wall-clock time followed by multiple columns of data, for example:

Begin HeartBeat Region_1_Heartbeat
  Stream Name = output
  At Step 0, Increment = 10

  precision is 5

  global step
  global timestep as dt
  global time
  global total_energy as te
End

+[12:18:51] step=240, dt=3.13933e-04, time=7.56578e-02, te=4.02795e-06
+[12:18:51] step=250, dt=3.13933e-04, time=7.87971e-02, te=1.32125e-06
+[12:18:51] step=260, dt=3.13933e-04, time=8.19365e-02, te=6.88142e-07
+[12:18:51] step=270, dt=3.13933e-04, time=8.50758e-02, te=3.93574e-06
+[12:18:52] step=280, dt=3.13933e-04, time=8.82151e-02, te=7.46609e-06
+[12:18:52] step=290, dt=3.13933e-04, time=9.13545e-02, te=1.03856e-05
+[12:18:52] step=300, dt=3.13933e-04, time=9.44938e-02, te=1.36822e-05
+[12:18:52] step=310, dt=3.13933e-04, time=9.76331e-02, te=1.64630e-05

The above example begins each line with a timestamp followed by five labeled data columns. The precision of the real data is 5. This example does not have a legend. This format can be modified with these commands.

9.8.7.1. CTH SpyHis output format

FORMAT = SPYHIS|ORIGINAL|CSV(CSV)

The FORMAT described the output format for the heartbeat file

FORMAT=SPYHIS specifies a particular spaced format that can be processed with the CTH SpyHis application as post-processor for time-history data.
FORMAT=ORIGINAL is a legacy format option. This format is similar to the default CSV option, but does not have a comment after the time stamp column.
FORMAT=CSV specifies a comma separated value format. This is the default format.

9.8.7.2. Specify floating point precision

PRECISION = <integer>precision

By default, the real data is written with a precision of 5 which gives 5 digits following the decimal point. This can be altered with the PRECISION command. If the command line PRECISION = 2 is specified, then the above data would look like:

Begin HeartBeat Region_1_Heartbeat
  ...
  precision = 2
  ...
End

+[12:18:51] step=240, dt=3.14e-04, time=7.57e-02, te=4.03e-06
+[12:18:51] step=250, dt=3.14e-04, time=7.88e-02, te=1.32e-06
+[12:18:51] step=260, dt=3.14e-04, time=8.19e-02, te=6.88e-07

The precision applies to all real data; it is not possible to specify a different precision for each variable.

9.8.7.3. Specify Labeling of Heartbeat Data

LABELS = <string>OFF|ON

The above example shows the default output which consists of a label and the data separated by ‘=.’ The existence of the labels is controlled with the LABELS command. If LABELS = OFF is specified, then the above data would look like:

Begin HeartBeat Region_1_Heartbeat
  ...
  labels = off
  precision = 2
  ...
End

+[12:17:37] 240, 3.14e-04, 7.57e-02, 4.03e-06
+[12:17:37] 250, 3.14e-04, 7.88e-02, 1.32e-06
+[12:17:38] 260, 3.14e-04, 8.19e-02, 6.88e-07

9.8.7.4. Specify Existence of Legend for Heartbeat Data

LEGEND = <string>OFF|ON

Outputting data without labels can make it easier to work with the data in a spreadsheet program or other data manipulation program, but with no labels, it is difficult to determine what the data represents. The LEGEND output will print a line at the beginning of the heartbeat output identifying the data in each column. For example:

Begin HeartBeat Region_1_Heartbeat
  ...
  legend = on
  labels = off
  precision = 2
  ...
End

+[12:17:37] Legend: step, dt, time, te
+[12:17:37] 240, 3.14e-04, 7.57e-02, 4.03e-06
+[12:17:37] 250, 3.14e-04, 7.88e-02, 1.32e-06
+[12:17:38] 260, 3.14e-04, 8.19e-02, 6.88e-07

9.8.7.5. Specify format of timestamp

TIMESTAMP FORMAT <string>"timestamp_format"

Each line of the heartbeat output is preceded by a timestamp which shows the wall-clock time at the time that the line was output. This can be useful to verify that the code is still running and producing output and to determine how fast the code is running. The default timestamp is in the format [12:34:56] specified by the format {small``[%H:%M:%S]``}. If a different format is desired, it can be specified with the TIMESTAMP FORMAT command line. The format must be surrounded by double or single quotes, and the format is defined to be the string between the first single or double quote and the last matching quote type. If a modified format is desired, the documentation for the UNIX strftime provides some details on time format specification. The example below shows a timestamp format delimited by [ and ]. The timestamp consists of an ISO-8601 date format followed by the current time.

...
     timestamp format "\{%F %H:%M:%S\}"
...
+\{2008-03-17 09:26:17\} 2212, 1.34244e-06, 2.96948e-03, 2.96948e-03
+\{2008-03-17 09:26:17\} 2213, 1.34244e-06, 2.97082e-03, 2.97082e-03
+\{2008-03-17 09:26:17\} 2214, 1.34244e-06, 2.97216e-03, 2.97216e-03
+\{2008-03-17 09:26:17\} 2215, 1.34244e-06, 2.97350e-03, 2.97350e-03
+\{2008-03-17 09:26:17\} 2216, 1.34244e-06, 2.97485e-03, 2.97485e-03

9.8.8. Monitor Output Events

MONITOR = <string>RESULTS|RESTART|HISTORY

It is sometimes a benefit to know when the code has written a new set of data to one of the other output files (restart output, history output, or results output). The heartbeat output will report this data if the MONITOR command line is specified. Each time output is performed to any of the monitored output types, a line will be written to the heartbeat file specifying the timestamp, the simulation time and step, and the label name of the output type. For example:

begin results output my_results
  at step 0, increment = 10
...
end results output results

begin heartbeat data hb
  stream name = stdout
  monitor = results
  labels = off
  legend = on
  timestamp format "{%F %H:%M:%S} "
  at step 0, increment = 2
  global step
  global timestep as dt
  global time
  element spring_engineering_strain at ``\#``
     element 1 as sp1
end

Will give the output:

....
+{2008-03-17 10:03:22}  718, 1.34244e-06, 9.63871e-04, 9.63871e-04
-{2008-03-17 10:03:22}  Results data written at time = 0.00096656,
step = 720. my_results
+{2008-03-17 10:03:22}  720, 1.34244e-06, 9.66556e-04, 9.66556e-04
+{2008-03-17 10:03:22}  722, 1.34244e-06, 9.69241e-04, 9.69241e-04
+{2008-03-17 10:03:22}  724, 1.34244e-06, 9.71926e-04, 9.71926e-04
+{2008-03-17 10:03:22}  726, 1.34244e-06, 9.74611e-04, 9.74611e-04
+{2008-03-17 10:03:22}  728, 1.34244e-06, 9.77296e-04, 9.77296e-04
-{2008-03-17 10:03:22}  Results data written at time = 0.00097998,
step = 730. my_results
+{2008-03-17 10:03:22}  730, 1.34244e-06, 9.79981e-04, 9.79981e-04
....

9.8.9. Automatically Add User Output Variables To HeartBeat

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.