Tree Correlator

#Motivation A correlator is an object relating events occurring in the same or different detectors at the same or different times. We have listed here the features of the original Correlator class and the new TreeCorrelator class.

##Features of Correlator

1. Tailored for DSSD experiments
2. Difficult to extend
3. Will drag a lot of unnecessary code if used for other purposes
4. Deeply bound into basic structures (composed into RawEvent class)

##Featuers of TreeCorrelator

1. Flexible design
2. Easy extending
3. Dynamic creation, easy modification for different experimental setups
4. Loosely bound building blocks, easy to remove if not needed
5. (More object oriented design)

#Design The basic building block of the TreeCorrelator is the Place. A Place is an abstract object, may be related with physical objects, conditions, or sets of conditions. For example, a place called "Beam On" may be activated when we receive a "Beam On" signal and deactivated when we receive the subsequent "Beam Off".

Each entry in the map node is related with a basic place. If you have defined a channel

<Channel number="0" type="generic" subtype="beta"/></Channel>

A place will automatically be created with the name generic_beta_0. The number at the end of the place refers to the location of the detector, which counts from zero for each type:subtype combination. Places are characterized by Boolean state (True / False) but also may store additional information (time, energy, etc.). Places should be kept simple, each serving one simple task only (e.g. counting number of activations, performing logical operation ’or’, etc.). User will be given a number of such building blocks to build a hierarchical tree scheme for his experiment. We will connect places with other places as we would connect analog electronics modules (e.g. noise discriminators, coincidence units, etc.).

#Usage ##Defining places - XML syntax

• Basic places are created automatically from entries in the map node. Their names are generated as type_subtype_location"
• Root element should be named , and may have description attribute
• Each element has following attributes.
  • Mandatory attributes:
    • name - required, if the last token (tokens are separated by ’_’) is in format X-Y,Z where X, Y and Z are integers, it will be interpreted as a list (e.g. beta_0-1,5,9-10 will create beta_0, beta_1, beta_5, beta_9 and beta_10 )
  • Optional attributes:
    • type - must be one of the known places. If type is not used or empty (type="") it is assumed that place already exists. In particular this is true for all basic places created from channels as defined in map node – replace - if set to ’true’, will replace existing place with a one defined in this element. – fifo - depth of FIFO of a place – coincidence - defines type of relation with parent (true of false) – low_limit, high_limit - required for PlaceThreshold and PlaceThresholdOR, defines threshold limits (units of calibrated energy).
    • reset - The place will be reset at the end of each event.

#Using places ##Accessing place's status

bool tapeMove = TreeCorrelator::get()->place("TapeMove")->status();

##Activating and deactivating place (if not done automatically!)

TreeCorrelator::get()->place("TapeMove")->activate(time);
CorrEventData info(time, energy);
TreeCorrelator::get()->place("TapeMove")->activate(info);
TreeCorrelator::get()->place("TapeMove")->deactivate(time);

##Accessing stored information

TreeCorrelator::get()->place("TapeMove")->last().time;
TreeCorrelator::get()->place("TapeMove")->secondlast().time;

###Rarely needed

TreeCorrelator::get()->place("TapeMove")->info_[i];

#Known Places

• Place - abstract base class
• PlaceLazy - abstract, does not store multiple activation / deactivation events
• PlaceDetector - most basic (does not depend on children)
• PlaceThreshold - activates if energy between low and high thresholds
• PlaceThresholdOR - as above but depends on children status (’or’ logic operation)
• PlaceCounter - counts number of activation
• PlaceOR - performs ’or’ logic operation on children status
• PlaceAND - performs ’and’ logic operation on children status
• PlaceSwitchANDX - switch–like behavior

#Example ##Map Node

<Map verbose_calibration="False" verbose_map="False" verbose_walk="False">
    <Module number="0">
        <Channel number="0" type="scint" subtype="beta"></Channel>
    </Module>
    <Module number="1">
        <Channel number="0" type="ge" subtype="clover_high"></Channel>
        <Channel number="1" type="ge" subtype="clover_high" ></Channel>
        <Channel number="2" type="ge" subtype="clover_high"></Channel>
        <Channel number="3" type="ge" subtype="clover_high" ></Channel>
        <Channel number="4" type="logic" subtype="mtc_start" ></Channel>
        <Channel number="5" type="logic" subtype="mtc_stop" ></Channel>
        <Channel number="6" type="logic" subtype="beam_start" ></Channel>
        <Channel number="7" type="logic" subtype="beam_stop"></Channel>
        <Channel number="8" type="ge" subtype="clover_high"></Channel>
        <Channel number="9" type="ge" subtype="clover_high" ></Channel>
        <Channel number="10" type="ge" subtype="clover_high"></Channel>
        <Channel number="11" type="ge" subtype="clover_high" ></Channel>
    </Module>
</Map>

##Tree Correlator Node

<TreeCorrelator name="root" description="LeRIBSS Style Experiment" verbose="False">
    <Place type="PlaceOR" name="Beta" fifo="10">
        <Place type="PlaceThreshold" name="scint_beta_0"
            low_limit="10.0" high_limit="16382" fifo="5"
            replace="true"/>
    </Place>

    <Place type="PlaceOR" name="Gamma">
        <Place type="PlaceOR" name="Clover0">
            <Place type="PlaceThreshold" name="ge_clover_high_0-3"
                low_limit="20.0" high_limit="99999"
                replace="true"/>
        </Place>
    </Place>

    <Place type="PlaceAND" name="GammaWOBeta">
        <Place type="" name="Gamma" coincidence="true"/>
        <Place type="" name="Beta" fifo="10" coincidence="false"/>
    </Place>

    <Place type="PlaceDetector" name="TapeMove" reset="false"/>
    <Place type="PlaceDetector" name="Beam" reset="false"/>
    <Place type="PlaceDetector" name="Cycle" reset="false"/>
</TreeCorrelator>

#ADVANCED!! - Adding a Place Type ##Places.hpp Create a new derived class.

class PlaceX : public Place {
      public:
           PlaceX(bool resetable = true, unsigned max_size = 2,
                  int parX) :
               Place(resetable, max_size) {
                   /*Possibly do something here*/
               }
      protected:
           virtual void check_(CorrEventData& info);
  };

##Places.cpp Define a function check_ (pure abstract in base class)

void PlaceX::check_(CorrEventData& info) {
    /* Function body */
}

##PlaceBuilder.hpp Add a the prototype for the new method

Place* createPlaceX(std::map<std::string, std::string>& params);

##PlaceBuilder.cpp Define the method and what you want it to do.

Place* PlaceBuilder::createPlaceX (map<string, string>& params) {
    bool reset = strings::to_bool(params["reset"]);
    int fifo = strings::to_int(params["fifo"]);
    int parX = strings::to_int(params["parX"]);
    Place* p = new PlaceX(reset, fifo, parX);
    return p;
}

##PlaceBuilder Finally, add function to the if–else loop, so XML will understand the new type.

if (type == "")
    return NULL;
(...)
else if (type == "PlaceX")
    return createPlaceX(params);

##TreeCorrelator.xml Add comment to config/examples/example.xml to tell us about your new Place.