``Pan'' is the Parity Analysis code for HAPPEX II and related experiments at Jefferson Lab. It is being developed and maintained by Richard Holmes, Robert Michaels, Bryan Moffit, Kent Paschke, Riad Suleiman, and Antonin Vacheret, with contributions from additional authors. This design document contains a description of requirements, programming rules, an overall description of the program, a list of classes and their responsibilities, program flow, and a UML conceptual class diagram.
The code must meet the following requirements.
Code developers will try to conform to the the following programming rules.
event.GetData("typo","error") you get a
warning.bool IsEpicsEvent() const;. Absence of
const implies the state of the object may (and probably will)
be changed by this method.class TaEvent;. This makes makefile dependencies
and maintenance simpler.static deque<TaEvent> fgEventQueue;
TaEvent fEvLeft.
Also see commenting recommendations.
``Pan'' can refer to the C++ analysis software generally or to one specific application built from that software.
The Pan application is a relatively simple application, appropriate to the straightforward nature of the analysis. When invoked with -f, -r, or -o command line options it finds a single run in a data file or in online data, finds the analysis control database entries corresponding to that run, and analyzes that run. Statistics are printed periodically, and a ROOT file containing processed data and analysis results as well as a results database file are created. Pan is compiled with ROOT allowing it to be used another way: when invoked with no -f or -r option a ROOT prompt is presented. Pan's classes are then available for use from the ROOT prompt or in ROOT macros.
Also built from the Pan classes are Panam, a GUI driven analyzer intended mainly for online monitoring, and libpan.a, a library containing the more generally useful Pan classes for use by other applications.
The most important classes of the analyzer are described here. We explain in words the responsiblity of the class. Classes are listed in a semi-logical order from "big" to "little". For details see the Pan Class Index, or follow the class name links to the THtml-generated class documentation. (Panam classes need to be added to this.)
Manages the overall analysis. Calling Init, InitLastPass, Process, and End in that order, once each, gives a 1-pass analysis of a run. For a 2-pass analysis call Init, Process, EndPass1, InitPass2, InitLastPass, Process, End. (For more on 1-pass and 2-pass analyses, see TaStatistics class description.)
This class treats the data of one run. The Init method initializes the event TTree, attaches the Coda file or online data, and gets the analysis control database. It initializes the storage of devices and cuts.
In the event loop, the NextEvent method is called to get and decode an event from the data stream. AddCuts is called after preprocessing each event, to update the list of cut intervals. AccumEvent and AccumPair accumulate statistics for results of event and pair analysis, respectively. PrintSlice and PrintRun write statistics summaries to STDOUT.
When analysis is complete, Finish is called to write and close the ROOT file.
Abstract base class of analysis. Derived classes include TaStandardAna (for standard physics analysis), TaFeedbackAna (for feedback-only analysis), TaADCCalib (for computation of pedestals and DAC noise slopes), and TaDebugAna (for debugging helicity signal problems, etc.; actually derives from TaStandardAna). Other specialized analyses, if needed, can be developed as new derived classes. Each of these is responsible for some treatment of VaEvents from a TaRun. The type of analysis to be done is specified in the analysis control database, and the TaAnalysisManager instantiates the appropriate analysis class accordingly.
VaAnalysis has initialization and termination routines for both the overall analysis and the analysis of a particular run. At present Pan is designed to analyze only a single run, but these routines provide for a possible future version that will handle multiple runs.
The main event loop is inside the ProcessRun method. The three main methods called from here are PreProcessEvt, ProcessEvt, and ProcessPair. The first of these places the most recently read event into a delay queue until the delayed helicity information for that event becomes available. Cut conditions are checked for here. Once the helicity information is added the event is pushed onto a second delay queue, while the events are used to construct pairs which are pushed onto a third delay queue. These two delay queues are used to hold events and pairs until we can tell whether they fall within a cut interval caused by a cut condition arising later. Events and pairs which emerge from the ends of these queues are analyzed in ProcessEvt and ProcessPair, respectively. Analysis results are added to the events and pairs themselves.
Provide an interface to an analysis control database in either of two forms: ASCII text files or a MYSQL database. The analysis control database is used to define run dependent parameters, such as the datamap, cut list, and calibrations.
Contains information on all the devices specified in the datamap (it's called TaDevice for historical reasons; perhaps TaDevices would be a better name). Initialized from the datamap by TaRun and used to decode the event data.
An event of data. This is a base class from which are derived TaEvent, corresponding to genuine events from the data acquisition system, and TaSimEvent, corresponding to events in which some data have been artificially generated for debugging purposes. These classes include methods to get data using keys. For ADCs and scalers can also get the data by slot number and channel. Events are loaded from a data source and may have analysis results added to them; they may be checked for cut conditions.
Base class for pairs of events of opposite helicities. Contains (when full) two events, as well as the results of analysis of that pair. Different derived classes correspond to different beam helicity structures. There are two derived classes, TaPairFromPair for analysis of data with HAPPEX-I style pair-oriented helicity structure, and TaPairFromQuad for analysis of data with G0 style quadruple-oriented helicity structure. (Note that no Pan structure corresponds to a quadruple; the only differences between these two classes are the checks they make on helicity structure.)
The Fill method is a bit tricky. When a
pair is created, it is empty (i.e., it has no events in it);
Fill takes a TaEvent object and, if it can't use
it immediately to create a pair, stores it in a static
container and returns false; if it can pair it
with a previously stored event, it fills the pair with those
two events and returns true. Methods are
provided to compute differences and asymmetries for a given
device.
A TaCutInterval consists of a cut type, a cut value, and two event numbers, corresponding to the start and end of the cut condition.
List of cuts intervals. The cut list for a given run identifies all the intervals during which a cut condition existed. It also contains extensions for each cut type, telling how many events to extend each interval before and after the stored event numbers; a tally of events failing each cut type; and labels for the cut types.
Results database files, for input and output respectively. See results_database.txt for details.
Object used to facilitate blind physics analysis.
Results of the analysis are vectors of these quantities, which have a label, a value, and a unit.
A general purpose statistics class, allowing accumulation of sums for one value or a set of values, from which quantities such as means, widths, errors, etc. can be computed.
Provides character data ROOT output for analysis control database.
Provides methods to generate Pan standard filenames.
Derives from STL string; provides additional methods. No additional storage is defined, so strings and TaStrings can be converted back and forth as needed; e.g. to convert a string to lowercase you can do something like
string mixedstring ("MixedCaseString");
TaString temp = mixedstring;
string lowerstring = temp.ToLower();
To show coarsely how the program flows from beginning to end, here is the Program Flow Diagram in PDF format.
This PDF Class Diagram illustrates the inheritence and close relationships in a UML style. The inheritences are illustrated by an open triangle type of arrow, which is the standard notation. The other relationships are in most cases containment, but in some cases simply usage. This diagram is old and somewhat obsolete, but still gives a fairly accurate picture of the class relationships.