# 9.7. 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.7.1 through Section 9.7.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.7.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.7.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.12 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.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>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.12 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.12 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.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>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.7.1.2, for obtaining heartbeat output. The command line in this section or the command line in Section 9.7.1.2 produces heartbeat files with variable information. The difference in these two command lines (Section 9.7.1.3 and Section 9.7.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.12 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.12 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.7.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.7.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.7.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.7.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.7.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.7.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.7.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.7.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.7.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.7.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.7.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.7.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.7.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.

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