From GlueXWiki
Revision as of 17:59, 14 April 2022 by Sdobbs (Talk | contribs) (Reaction Definition)

Jump to: navigation, search


The basic concept of the ReactionFilter Plugin is to use a defined physics reaction, usually described in a configuration file, to analyze the reconstructed data (REST files) event by event testing the hypothesis of the proposed reaction. It creates an output root file referred to as Physics Analysis Root Tree (PART) which in turn will be analyzed by other code like the DSelector.

The plugin applies basic PID selection criteria (time, mass, and dEdx) and by default a Kinematic Fitter to the reconstructed charged track and/or neutral showers of each event and applies the Kinematic Fitter based on the chosen reaction requirements.


The ReactionFilter plugin is located in ReactionFilter plugin on github and depends heavily on the Analysis Library all of which are part of the halld_recon package.

While the analyzers will usually not need to run this plugin by themselves, since this is generally done by the responsible operator who runs an analysis launch with all requested reactions from all analyzers at once for the sake of efficient use of computing resources. However, it is useful for any analyzer to understand the concept of the ReactionFilter plugin and its functionality, particularly since an analyzer needs to to provide the definition of the reaction to the operator of the analysis launch.

  • An introduction to the use of the ReactionFilter plugin can be found in this DocDB document (at presentation). Its code is based on information that can be found in Analysis DReaction. This latter link also serves as a guide to write your own analysis reaction plugin if so desired or needed.
  • The use of the Reaction Filter requires the definition of a reaction. For examples of reaction definitions and an easy form to define them, examine the online submission form: Create a Reaction Config File
  • Important: Generally an analysis reaction request is submitted to the global analysis system administrator using the above link, who will run the reaction over the specified data set for all submitted reactions in one go. So the user will be provided with the resulting PART files. These files will have the specified reaction in their file name.
  • This step by the administrator is called an Analysis Launch and details can be found here: Analysis Launch and Monitoring
  • The output data (PART) will be located on the cache disk system of the jlab computing system. An example of such a location is /cache/halld/RunPeriod-2018-01/analysis/ver19/. This file system is backed by tape storage - if the PART files are not on the cache disks, they may have been retrieved from tape. The data is discriminated by Run-Period and version the latter referring to the number of the analysis launch that was performed. Note that each launch usually uses the latest version of the analysis software.

Reaction Definition

The definition of a reaction in a configuration file will look something like this:

Reaction1 1_14__7_8_9_17_14
Reaction1:Flags B2_T1_S1_M7_M17
  • The first line "Reaction1" defines the reaction in this case reaction number 1. The first part before the "__" represents the initial state, in this case 1(γ) on 14(proton target). The second part (after "__") represents the final state, in this case 7(π0), 8(π+), 9(π-), 17(η) and 14(proton). The number coding of the particles is defined in particleType.h.
  • If a particle is assumed but not detected, it can be specified with 'm' (e.g. a missing pi0 is m7). A missing 'unknown' particle m0 can be used for fully inclusive reactions. The missing particle type is used for the loose missing mass cuts and kinematic fit constraints applied in the analysis library.
  • The second line "Reaction1:Flags" defines the flags associated with this reaction.
    • B2 : include beam photons from two beam bunches on either side of the prompt peak (default B1)
    • T1 : exclude events with more than one additional reconstructed charged track (default T3)
    • S0 : exclude events with any additional showers in time with the reconstructed reaction (events with time pileup are excluded)
    • S1 : exclude events with more than one additional reconstructed shower in time the reconstructed reaction (default 999 and events with time pileup are not excluded)
    • M7 : do NOT constrain the π0 mass in the kinematic fit
    • M17: do NOT constrain the η mass in the kinematic fit
  • Other Flags are:
    • F# : Kinematic Fit type; 0 (none), 1, 2, 3, 4 (default). For the definitions of these numbers, see the "Kinematic Fitter" section below.
    • U1 : Save all unused particles in the output root tree file (will increase output root file size!)
  • By default a π0 will decay into two photons and similarly the η. A full list of default decay channels of various particles can be found in the code of the Reaction Filter Factory (line #34).
  • Explicit decay modes can be specified for particles. For example, requesting the η to decay into π0, π+, π-:
    • Reaction1:Decay1 17__7_8_9
    • The "1" at the end of "Decay" is a counter, this allows for more than one Decay definition in a reaction.
    • All particles of the same type (in a reaction) will decay into the same channel. So if there would be two etas in the reaction both would be reconstructed in their decay into the same channel.


This section shortly touches on the concept of what a Combo is. Each event has a certain number of reconstructed charged particle tracks and neutral particle showers based on the data recorded in the GlueX detector. The combination of these particles form the final state. In addition the data from the tagger detectors provide reconstructed beam photons representing options for the initial state. For each event the Reaction Filter will test all possible combinations of initial and final state reconstructed particles that match the defined reaction and uses the kinematic fitter to apply energy and momentum conservation criteria as well as other criteria like timing to test the validity of each such combination called Combo.

Any combination with which the kinematic fitter does converge will be saved to the output tree together with the results from the kinematic fitter.

Kinematic Fitter

Kinematic fitting is a mathematical procedure in which one uses the physical laws governing a particle interaction or decay to improve the measurements of the process. A kinematic fit to experimental data can set constraints on four-momentum conservation, decaying particle invariant mass, and common particle vertices. All of these constraints can be applied simultaneously for any, arbitrarily complex, physics reaction. Both detected and decaying particles can be used to constrain common vertices. In common-vertex fits, photons are treated as measured calorimeter showers rather than reconstructed particles, allowing their momentum to change as the estimate for the common-vertex changes. The uncertainty of all measurements is taken into account via covariance matrices.

In the ReactionFilter plugin, 4 different settings are commonly used:

  1. F0: no kinematic fit is applied, only the measured quantities for the particles are saved
  2. F1: 4-Momentum constrains, which includes momentum, energy and invariant mass
  3. F2: Vertex constrains, which takes into account primary and all secondary vertices
  4. F4: 4-Momentum and Vertex contrains (default)

For FX and X>0, by default, only events with a fit converging are saved. To save events when the fit is not converging this option should be added: ANALYSIS:KINFIT_CONVERGENCE 0. There are more options, but they are not properly tested. Detailed information about the implementation can be found in GlueX-doc-2112.