Hall A Analyzer

h1. How to write a detector class for the C++ analyzer

{{TOC}}

h2. Getting started

Before you start programming your new detector class, you will need to make a few decisions:

* Which apparatus(es) will your detector belong to? If it is an existing apparatus, for example @THaHRS@, then your detector class needs to be included in that apparatus's list of detectors. Including it there is very easy, just use the @AddDetector()@ or write a derived apparatus class that creates the detector in its constructor (see adding and removing detectors). If it is a new apparatus (e.g. a new spectrometer), you will need to write a class for it as well (see creating an Apparatus.)

* Does you detector resemble an existing detector? For example, a new scintillator should normally resemble the existing scintillators (@THaScintillator@). If so, you may be able to use the existing class. You will need to think of a unique name for the detector and compile a new database entry for it, in particular geometry information (e.g. number of paddles).

If an existing detector class is not suitable for your detector, e.g. because the behavior of some functions needs to be different, then you should let your new class to inherit from the existing class, overriding only those functions that must do different things.

To emphasize: It is *not* always necessary to write a new class for a new detector! If you have several essentially identical detectors (e.g. scintillators), you should try to write a *single* class that can handle all of them. Each object of this class type will then represent one of these detectors. The individual detectors are distinguished by their unique name (see naming conventions).

* If your detector does not resemble any existing one, then your detector class should inherit directly from one of the generic detector classes:

** @THaDetector@ is the simplest base class. It can be used for beamline instrumentation (e.g. @THaBPM@) and similar miscellaneous equipment.

** @THaSpectrometerDetector@ is a @THaDetector@ to be included in a Spectrometer (@THaSpectrometer@). Actual detector classes should not inherit directly from this class, but rather from one of the following three, unless you know exactly what you are doing.

** @THaTrackingDetector@ can be used as a base class for implementing tracking detectors such as VDCs. Here, a "tracking detector" represents equipment that is used to find the "physics tracks" in the spectrometer. In general, "physics tracks" are tracks that can be used for target/vertex reconstruction.

Some detectors, such as an FPP, do reconstruct tracks, but those tracks are not the "physics tracks". Rather, they are "instrumentation tracks" that are used within the detector only. Thus, an FPP should not be a @THaTrackingDetector@, but rather a @THaNonTrackingDetector@.

** @THaNonTrackingDetector@ is the base class for any spectrometer detectors that are not tracking detectors, e.g. scintillators.

** @THaPidDetector@ is a specialized @THaNonTrackingDetector@ that provides support for PID. Use it as the base class for all true PID detectors, e.g. Cherenkovs and shower counters.

For performance reasons, do not use this class if your detector currently does not do any PID calculations, even though it might in principle be used for PID (e.g. scintillators). If you add PID calculations later, all you have to do is change the class inheritance to add PID support.

If appropriate, create your own detector subclass structure, e.g. @THaPidDetector@ <- @THaCherenkov@ <- @THaGasCherenkov@. This might result in a cleaner design and might help avoid code duplication. However, be careful not to overcomplicate things. The above scheme for Cherenkovs could be useful if there is at least one common method for all Cherenkovs (e.g. PID processing). 

Once you have decided where your new detector fits into the class hierarchy, take one of the existing classes as a template and start rewriting it. There are a few requirements to keep in mind. Your class must

* follow the coding standards for the analyzer;

* inherit from @THaDetector@ or one of its subclasses;

* define a @Decode()@ method;

* if it is a @THaNonTrackingDetector@, define a @CoarseProcess()@ and @FineProcess()@ method; these can be dummy routines if no special processing is needed or if you don't know yet what best to do here;

* if it is a @THaTrackingDetector@, define a @CoarseTrack()@ and @FineTrack()@ method; again, these can be dummy routines if appropriate. 

Also, your class should define appropriate initialization routines, i.e. an @Init()@ method and/or a @ReadDatabase()@ and/or @DefineVariables()@ method. These methods should obtain all detector-specific parameters (geometry, mapping, calibrations, etc.) from a database and should register any symbolic variables to be accessible for dynamic tests and histograms in the global variable list @gHaVars@.

A simple example for a detector class is the generic scintillator class @THaScintillator@.

h2. Initialization

Every detector must have a public Init() method of type

<pre>

THaAnalysisObject::EStatus Init( const TDatime& date )

</pre>

This method should obtain all detector-specific parameters (geometry, mapping, calibrations, etc.) from the database. It should not be called from the constructor(s). @Init()@ is called by the standard analyzer at the beginning of the analysis of a run. The @TDatime@ object that is passed contains the time stamp of the prestart event of the run. It should be used to do time-dependent initializations, such as retrieving appropriate calibration parameters from the database. While you can write your own Init() function, it is recommended that you use the default @Init()@ provided by the @THaAnalysisObject@ base class. This default function will establish the connection to the database for you. In analyzer version 1.0, the database is simply a collection of plain text files. There is support time-dependence with a 1-day granularity and less (see database). If you do use the default @Init()@ method, you should (but do not have to) implement one or both of the following methods in your detector class. (These methods may be protected to prevent direct calls.)

<pre>

virtual Int_t ReadDatabase( const TDatime& date )

virtual Int_t DefineVariables( Emode mode )

</pre>

The first action in @ReadDatabase()@ should be to open the plaintext database file corresponding to the detector (as determined by the detector's and containing apparatus's names) as well as the time stamp of the current run. A convenience function @OpenFile()@ is available for this purpose. You can use the @FILE*@ handle returned by @OpenFile()@ with standard C file I/O commands (@fscanf@, @fgets@ etc.) to read the file. The file must be closed before leaving @ReadDatabase()@.

@DefineVariables()@ is called after @ReadDatabase()@ and should be used for setting up global symbolic variables. If your detector does not need a database file, you can put your initializations either in @Init()@ or in @DefineVariables()@, or write a @ReadDatabase()@ method that does not actually open any files. If you do not need any initialization, you do not need to implement any functions.

h2. Global Variables

Any data of your detector that you want to be accessible within the global analyzer context should be registered as global symbolic variables in the global list @gHaVars@. Any variables that you want to have available in tests/cuts or output to a ROOT file must be registered in this way. You can register variables either with a series of calls to

<pre>

gHaVars->Define( ... )

</pre>

or with a single call to

<pre>

DefineVariables( const VarDef* vars )

</pre>

The second form is recommended. Both forms can be mixed since @DefineVariables()@ simply make the appropriate calls to @Define()@. You must call @Define()@ explicitly in order to define multidimensional arrays.

@VarDef@ is an array whose entries have the structure (see @VarDef.h@)

<pre>

struct VarDef {

  const char*      name;     // Variable name

  const char*      desc;     // Variable description

  Int_t            type;     // Variable data type (see VarType.h)

  Int_t            size;     // Size of array (0/1 = scalar)

  const void*      loc;      // Location of data

  const Int_t*     count;    // Optional: Actual size of variable size array

};

</pre>

A typical sequence for defining global variables would be

<pre>

#include "VarDef.h"

VarDef vars[] = {

  { "nhit", "Number of hits",  kInt,   0,      &fNhit },

  { "adc",  "ADC values",      kFloat, fNelem, fADC },

  { "csum", "Cluster sums",    kFloat, MAXCLU, fCsum, &fNclusters },

  { NULL }

};

DefineVariables( vars );

</pre>

This will register three global variables called "@nhit@", "@adc@", and "@csum@", prefixed with the apparatus name and detector name, _e.g._ "@L.s1.nhit@". The data types (@kInt@, @kFloat@, see @VarType.h@) *must* correspond exactly to the types of the variables (5th field). "@nhit@" is a scaler (@size = 0@), "@adc@", a fixed-size array of size @fNelem@, and "@csum@" is a variable-size array of maximum size @MAXCLU@ and actual size contained in the variable fNclusters. The actual size is allowed to change from event to event. The 5^th^ field (@&fNhit@, @fADC@, @fCsum@) must be the address of the variable or the first array element. (You could also write @&fADC[0]@ instead of @fADC@ if you like to type a lot.) The 6^th^ field (@&fNclusters@), if not @NULL@, *must* be the address of a variable of type @Int_t@. (If the 6^th^ field is not specified, it is automatically initialized to @NULL@.) The definitions *must always* end with a final @{ NULL }@ entry or your program will crash.

h2. Decoding

Every detector must have a @Decode()@ method. It must be of type

<pre>

Int_t Decode( const THaEvData& evdata )

</pre>

Within the standard analyzer, Decode() will be called for every physics event. (You can override this behavior if you use your own apparatus class.) The event's raw data can be accessed via the methods of the @THaEvData@ object that is passed as the argument of Decode(). At the minimum, your Decode() function should find the detector's information in the event buffer and move it to data members of your class. Of course you may apply further processing if appropriate.

Within @Decode()@ you must only do processing that does not require information from any other detectors. If you need information from other detectors, put the corresponding code either in the @CoarseProcess()@/@CoarseTrack()@ or @FineProcess()@/@FineTrack()@ method of the detector class or in the @Reconstruct()@ method of the apparatus class to which your detector belongs.

h2. Coarse processing

The @CoarseProcess()@ method is relevant only for non-tracking detectors. Its type is

<pre>

Int_t CoarseProcess( TClonesArray& tracks )

</pre>

In the standard analyzer, @CoarseProcess()@ is called for every non-tracking detector after @CoarseTrack()@ has been called for all tracking detectors. Information on the tracks found for the current event, if any, is passed in the @TClonesArray@. This array contains zero or more @THaTrack@ objects. The track information is "Coarse", i.e. only preliminary reconstruction has been performed.

Here is a simple example how to retrieve the information from all tracks passed in the array:

<pre>

#include < THaTrack.h >

int ntrack = tracks.GetLast()+1; 

for( int i = 0; i < ntrack; i++ ) {

  THaTrack* theTrack = static_cast < THaTrack* > ( tracks.At(i) );

  if( !theTrack ) continue;

  Double_t fpx    = theTrack->GetX();     // x-position in fp

  Double_t fpy    = theTrack->GetY();     // y-position in fp

  Double_t fpth   = theTrack->GetTheta(); // theta wrt normal to fp

  Double_t fpph   = theTrack->GetPhi();   // phi wrt fp x-axis

  //... do computations ...

}

</pre>

Within @CoarseProcess()@, you cannot generally use information from any other detectors except tracking detectors. There is no guarantee that the non-tracking detectors are processed in any particular order. Therefore, this method should operate only on the tracks passed in the array.

h2. Fine processing

Like @CoarseProcess()@, the @FineProcess()@ method is relevant only for non-tracking detectors. Its type is

<pre>

Int_t FineProcess( TClonesArray& tracks )

</pre>

@FineProcess()@ is called for every non-tracking detector after all focal-plane track reconstruction has been done by the tracking detectors. Thus, this method should be used for any detector-specific processing that requires precise track information. Track information can be obtained from the @TClonesArray@ of @THaTracks@ in the same manner as described above for @CoarseProcess()@.

Within @FineProcess()@, you can use all "coarse processing" information from all other detectors as well as all information from all tracking detectors. To access information from another detector, either retrieve a global physics variable defined by that detector or use the public interface of that detector. For example:

<pre>

// Retrieve global physics variable called "r.s.x"

#include "THaVarList.h"

#include "THaVar.h"

Double_t x = kBig;

THaVar* pvar = gHaVars->Find("r.s.x");

if( pvar )

  x = pvar->GetValue();

</pre>

or

<pre>

// Call method GetX() of detector "mydet"

#include "THaApparatus.h"

#include "THaMyDet.h"       //as appropriate

Double_t x = kBig;

THaMyDet* mydet = static_cast< THaMyDet* >( fApparatus->GetDetector("mydet"));

if( mydet )

  x = mydet->GetX();

</pre>

h2. Coarse tracking

This method is only relevant for tracking detectors. It has the type

<pre>

Int_t CoarseTrack( TClonesArray& tracks )

</pre>

@CoarseTrack()@ is called immediately after @Decode()@ has been called for all detectors. The @TClonesArray@ of tracks is empty when the function is called and is intended to be an output variable. Tracking detectors are not guaranteed to be processed in a particular order, so the only information that can be assumed to be valid in this function is the decoded data for all detectors.

@CoarseTrack()@ is expected to reconstruct tracks from the decoded data in the fastest possible way, create @THaTrack@ objects, and put them in the output array. For convenience, the @THaTrackingDetector@ base class defines a method @AddTrack@ that can be used to add tracks to the array. This method should be be used for this purpose unless there is a good reason not to.

h2. Fine tracking

Like @CoarseTrack()@, this method is only relevant for tracking detectors. It has the type

<pre>

Int_t FineTrack( TClonesArray& tracks )

</pre>

@FineTrack()@ is called after @Decode()@, @CoarseTrack()@, and @CoarseProcess()@ have been executed for all detectors. Upon entry, the @TClonesArray@ of tracks contains the tracks found by @CoarseTrack()@. Tracking detectors are not guaranteed to be processed in a particular order, so the only information that can be assumed to be valid in this function is the decoded and coarse-processed data for all detectors.

@FineTrack()@ is expected to reconstruct tracks in the most precise way possible, using the decoded data and the coarse tracks as input. The function should modify the tracks already present in the input array rather than add new tracks. @THaTrack@ provides several @Set()@ methods that allow altering track data.