Project

General

Profile

Paths

Processing of events (and runs and subruns) occurs via the processing of paths. There are two kinds of path supported by art:

  • Trigger path: a configured sequence of module labels, each of which correspond to either a producer or filter (i.e. an event-modifying module).
  • End path: a configured sequence of module labels, each of which correspond to either an analyzer or output module (i.e. an event-observing module).

You should keep in mind a few things:

  • A path cannot be constructed that contains a mixture of event-modifying and event-observing modules. Attempting to do so will result in a run-time error.
  • The order in which trigger paths are processes is unspecified. You should not rely on any ordering.
  • For a given trigger path, the framework will execute the modules in the path according to the order the user specified.
  • All end paths are executed after all trigger paths have been processed--it is safe to rely on this behavior.
  • The order in which end-path modules are executed is unspecified.

Consider the following configuration:

physics: {

  producers: {
    p1: {}
    p2: {}
    p3: {}
  }

  filters: {
    f1: {}
  }

  analyzers: {
    a1: {}
  }

  tp1: [p1, p3]
  tp2: [p1, f1, p2]
  ep: [a1, o1]  
}

outputs.o1: {}

The trigger paths are tp1 and tp2; the end path is ep. The framework does not guarantee that tp1 will be processed before tp2 is. However, for tp1, the framework guarantees that p1 will be executed before p3, and that for tp2, the execution order will be p1, f1, and then, if the event passes filter f1, process p2.

Elided processing steps

Since the producer labeled p1 has been included in both paths tp1 and tp2, there might be concern that the p1 module is executed twice for each event. This is not the case. art guarantees that for a given module label, the corresponding module is executed only once per event, even if that module label is shared among multiple paths. This processing elision results in efficient workflows.

Path-behavior modification

Whenever a filter module is processed, the return value of the event-level call is a boolean of true, meaning continue processing the modules in the path, or false, which means that processing for that path should stop immediately. In the configuration example above, the tp2 path has the filter f1 between producers p1 and p2. This means that the p2 module is processed only if the f1 event-level call returns true. In some cases, it might be desirable to invert the boolean return value of f1, or to ignore it completely. To achieve this behavior, the configuration should be modified to be:

tp2a: [p1, "!f1", p2]  # process p2 only if f1 returns 'false', or
tp2b: [p1, "-f1", p2]  # ignore the boolean value of f1, and process p2 unconditionally

Note that if either the invert character ('!') or ignore character ('-') is used, it and the module label it prefaces must be surrounded by quotation marks. Not doing so results in a FHiCL-parsing failure. These characters cannot be used in combination, nor can they be applied to modules other than filters.

The trigger_paths and end_paths keywords

It is almost never necessary to additionally specify the trigger_paths and end_paths keywords in your job configuration. By default, all specified paths will be executed. The only time when the trigger_paths and/or end_paths keywords should be used is whenever it is desired to not execute one of the specified paths. For example, suppose for debugging reasons that somebody would like to process only path tp1 and not tp2. This can be achieved by including only the tp1 trigger-path name in the trigger_paths sequence:

physics: {
  ...
  tp1: [p1, p3]
  tp2: [p1, f1, p2]
  ...
  trigger_paths: [tp1]  # Process only tp1, and not tp2
}

We generally discourage this kind of workflow--if somebody is wanting to easily compare configurations, it becomes difficult to do so when the above configuration is used instead of

physics: {
  ...
  tp1: [p1, p3]
  # tp2: [p1, f1, p2] commented out!
  ...
}

even though the consequent event-processing is identical. Furthermore, if comparisons are performed via a checksum of the configuration, the checksums can be different even though the resulting physics content is identical. For these reasons, we do not encourage routinely using the trigger_paths and end_paths keywords.