Line data    Source code

       1           0 : \cond NEVER
       2             : Distributed under the MIT License.
       3             : See LICENSE.txt for details.
       4             : \endcond
       5             : 
       6             : # Events and triggers {#tutorial_events_and_triggers}
       7             : 
       8             : \tableofcontents
       9             : 
      10             : The "events and triggers" infrastructure (and the related "events and
      11             : dense triggers") provide some control of SpECTRE executable execution
      12             : from the input file contents by running user-specified code on the
      13             : elements.  It does not generally have major effects on the flow of the
      14             : \ref dev_guide_parallelization_core_algorithm "algorithm", but is
      15             : primarily used for observations, such as writing volume data to H5
      16             : files, and minor simulation adjustments.
      17             : 
      18             : ### Events
      19             : 
      20             : An \ref Event "event" is an input-file-creatable object that performs
      21             : some task that (with the exception of the \ref Events::Completion
      22             : "Completion" event) does not directly affect the execution of the
      23             : algorithm on the element.  The effects of events are limited to
      24             : sending messages.  The most commonly used events (such as the \ref
      25             : ::Events::ObserveNorms "ObserveNorms" event) send data to
      26             : be written to disk, but have no long-term effects on the simulation
      27             : state.  Others (such as \ref Events::ChangeSlabSize "ChangeSlabSize")
      28             : can have indirect effects when \ref dev_guide_parallelization_actions
      29             : "actions" react to the messages they send.
      30             : 
      31             : ### Triggers
      32             : 
      33             : A \ref Trigger "trigger" is an input-file-creatable object that
      34             : controls when events are run.  They are checked periodically, once per
      35             : Slab in an evolution executable, and once per iteration in an elliptic
      36             : solve.  At each check a trigger may fire, causing its associated
      37             : events to run or not.  Triggers must give a consistent result over
      38             : the entire domain at each check, so their result must always be
      39             : independent of element-specific state, such as the local values of the
      40             : system variables.
      41             : 
      42             : ### Dense triggers
      43             : 
      44             : A \ref DenseTrigger "dense trigger" is similar to a trigger, but uses
      45             : time-stepper dense output (i.e., interpolation or extrapolation) to
      46             : provide more precise control of the time that it fires.  As a
      47             : time-related feature, dense triggers are only applicable to evolution
      48             : executables.  Dense triggers fire at a precise set of times,
      49             : independent of the time-step or slab state, by interpolating the
      50             : evolved variables to the requested time before running the associated
      51             : events.  As with normal triggers, dense triggers are required to fire
      52             : consistently over the entire domain.
      53             : 
      54             : ### Input file syntax
      55             : 
      56             : The `%EventsAndTriggers` (and `%EventsAndDenseTriggers`) sections of
      57             : the \ref dev_guide_option_parsing "input file" are parsed as a list of
      58             : Trigger/Events pairs:
      59             : 
      60             : \snippet PlaneWave1DEventsAndTriggersExample.yaml multiple_events
      61             : 
      62             : In this example, we are using the \ref Triggers::Slabs "Slabs" trigger
      63             : to run two events every 10 slabs: ObserveFields and
      64             : \ref ::Events::ObserveNorms "ObserveNorms". We also run the
      65             : \ref ::Events::Completion "Completion" event at the
      66             : \ref ::Triggers::Always "Always" trigger, so the run will terminate immediately.