Triggers

Triggers allow the user to specify a set of actions that are triggered by the result of a boolean expression. Triggers leverage the query and expression system to enable a set of primitives to create custom tailored triggers for simulations. There are several motivations that make triggers useful. Examples include cost reduction (time) and debugging (correctness).

Cost Reduction

Visualization and analysis operation are not free, i.e., performing them takes time. One example is that rendering an image every simulation cycle might be a relatively high cost. Another example is performing a potentially time consuming operation like flow field analysis may might need to take place at a lower frequency than each time ascent.execute(actions) is called or may need to execute only when a specific simulation event occurs.

Debugging

Triggers can be a useful tool in detecting anomalous conditions while a simulation is running. For example, triggers can detect of the minimum or maximum values of a field are outside the expected ranges and dump out the mesh and related field for inspection inside of VisIt.

Simple Example

A trigger requires a trigger condition and a actions file:

-
  action: "add_triggers"
  triggers:
    t1:
      params:
        condition: "cycle() % 100 == 0"
        actions_file : "my_trigger_actions.yaml"

In this example, the trigger will fire when the current cycle is divisible by 100.

Queries and Triggers

Triggers can leverage the query system, and combining both queries and triggers creates a rich set of potential options for triggers.

Debugging

The following code example shows how queries and triggers can be used for debugging:

-
  action: "add_queries"
  queries:
    q1:
      params:
        # get the maximum value of a field
        expression: "max(field('pressure'))"
        name: "max_pressure"
    q2:
      params:
        expression: "1e300"
        name: "crazy_value"
-
  action: "add_triggers"
  triggers:
    t1:
      params:
        condition: "max_pressure > crazy_value"
        actions_file : "my_trigger_actions.yaml"

In the above example, the trigger will fire if the maximum value of pressure exceeds crazy_value. A useful actions file might dump the mesh to a hdf5 file for later inspection.

Event Detection

The following code example shows how queries and triggers can be used for to detect a jump in entropy that could represent a simulation event that the user wants act on:

-
  action: "add_queries"
  queries:
    q1:
      params:
        expression: "entropy(histogram(field('pressure')))"
        name: "entropy"
-
  action: "add_triggers"
  triggers:
    t1:
      params:
        condition: "history(entropy, relative_index = 1) - entropy > 10"
        actions_file : "my_trigger_actions.yaml"

In the above example, the trigger will fire if the change in entropy changes by more than 10 in positive direction.