SpECTRE  v2022.10.04
Events and triggers

The "events and triggers" infrastructure (and the related "events and dense triggers") provide some control of SpECTRE executable execution from the input file contents by running user-specified code on the elements. It does not generally have major effects on the flow of the algorithm, but is primarily used for observations, such as writing volume data to H5 files, and minor simulation adjustments.

## Events

An event is an input-file-creatable object that performs some task that (with the exception of the Completion event) does not directly affect the execution of the algorithm on the element. The effects of events are limited to sending messages. The most commonly used events (such as the ObserveNorms event) send data to be written to disk, but have no long-term effects on the simulation state. Others (such as ChangeSlabSize) can have indirect effects when actions react to the messages they send.

## Triggers

A trigger is an input-file-creatable object that controls when events are run. They are checked periodically, once per Slab in an evolution executable, and once per iteration in an elliptic solve. At each check a trigger may fire, causing its associated events to run or not. Triggers must give a consistent result over the entire domain at each check, so their result must always be independent of element-specific state, such as the local values of the system variables.

## Dense triggers

A dense trigger is similar to a trigger, but uses time-stepper dense output (i.e., interpolation or extrapolation) to provide more precise control of the time that it fires. As a time-related feature, dense triggers are only applicable to evolution executables. Dense triggers fire at a precise set of times, independent of the time-step or slab state, by interpolating the evolved variables to the requested time before running the associated events. As with normal triggers, dense triggers are required to fire consistently over the entire domain.

## Input file syntax

The EventsAndTriggers (and EventsAndDenseTriggers) sections of the input file are parsed as several nested YAML lists representing vectors and pairs. The outermost list is a vector with one entry for each trigger. The entries in this vector are two-element lists representing pairs whose first elements are triggers and whose second elements are a third level of list containing the events.

EventsAndTriggers:
- - Slabs:
EvenlySpaced:
Interval: 10
Offset: 0
- - ObserveFields:
SubfileName: Fields
VariablesToObserve: [Psi]
InterpolateToMesh: None
CoordinatesFloatingPointType: Double
FloatingPointTypes: [Double]
- ObserveNorms:
SubfileName: Errors
TensorsToObserve:
- Name: Error(Psi)
NormType: L2Norm
Components: Sum
- Name: Error(Phi)
NormType: L2Norm
Components: Sum
- Name: Error(Pi)
NormType: L2Norm
Components: Sum

In this example, we are using the Slabs trigger to run two events every 10 slabs: ObserveFields and ObserveNorms.

If an event and trigger both took no options, the syntax

- - Always
- - Completion

could be written in the more familiar form

- [Always, [Completion]]

but we recommend always using the expanded form for consistency.