Hall A Analyzer

h1. How to write an apparatus class for the C++ analyzer

14 June 2003

An apparatus is a collection of detectors that work together and should be analyzed as a group. For this reason, the [[Standard Algorithm|standard analyzer]] does not analyze detectors individually, but only as part of an apparatus.

h2. Creating a completely new apparatus

Writing a class for a completely new apparatus, _i.e._ one that does not resemble an existing one at all, like a new type of spectrometer, may vary in complexity from relatively simple to quite complicated. From a programming point of view, your new apparatus class should inherit from

* "@THaApparatus@":http://hallaweb.jlab.org/podd/html/THaApparatus.html if you want to create a generic apparatus such as a collection of beamline or target instrumentation; or

* "@THaSpectrometer@":http://hallaweb.jlab.org/podd/html/THaSpectrometer.html if you want to create a new spectrometer that is capable of particle tracking and, possibly, PID. 

h3. Generic apparatus

In the first case (generic apparatus), you must write a @Reconstruct()@ method. This can be a dummy if you only want to decode the detectors. This function is expected to do any processing that combines results from different detectors within the apparatus, for instance using tracks found by wire chambers to locate clusters in a shower counter. Since @THaApparatus::Reconstruct()@ is a pure virtual function, you will not be able to instantiate any objects of your class unless this method is implemented.

You can create the detector objects associated with the apparatus in the constructor or add them later via "@AddDetector@":http://hallaweb.jlab.org/podd/html/THaApparatus.html#THaApparatus:AddDetector.

h3. Spectrometer apparatus

In the second case (spectrometer), you can take advantage of the infrastructure already implemented by the "@THaSpectrometer@":http://hallaweb.jlab.org/podd/html/THaSpectrometer.html base class. In particular, @THaSpectrometer@ provides a fairly generic @Reconstruct()@ method (see [[Standard Algorithm]]). At the minimum, your spectrometer apparatus class must

* provide a @TrackCalc()@ method. @TrackCalc()@ is called by "@THaSpectrometer::Reconstruct()@":http://hallaweb.jlab.org/podd/html/THaSpectrometer.html#THaSpectrometer:Reconstruct to compute particle track properties such as momentum and beta right after the @FineProcess()@ stage of the analysis. This can be a dummy function if no such calculations are necessary;

* provide a @FindVertices()@ method. @FindVertices()@ is called by @THaSpectrometer::Reconstruct()@ at the end of processing to reconstruct tracks to the target. Again, this can be a dummy function if no such reconstruction is necessary.

You may create the detector objects of your spectrometer in its constructor, but this is only recommended if the detector configuration is not expected to change. Spectrometers with variable detector configurations should instead be configured using "@AddDetector@":http://hallaweb.jlab.org/podd/html/THaApparatus.html#THaApparatus:AddDetector calls from the analysis steering script.

As with generic apparatuses, @THaSpectrometer::TrackCalc()@ and @THaSpectrometer::FindVertices()@ are pure virtual functions, and so you will not be able to instantiate any objects of your class unless these methods are implemented.

Additionally, you can override any of the other virtual functions of "@THaApparatus@":http://hallaweb.jlab.org/podd/html/THaApparatus.html and "@THaSpectrometer@":http://hallaweb.jlab.org/podd/html/THaSpectrometer.html. Some obvious candidates are

* "@Reconstruct()@":http://hallaweb.jlab.org/podd/html/THaSpectrometer.html#THaSpectrometer:Reconstruct, _e.g._ to implement a different order of processing and computations;

* "@CalcPID()@":http://hallaweb.jlab.org/podd/html/THaSpectrometer.html#THaSpectrometer:CalcPID, to modify the way PID is handled. 

h2. Modifying an existing apparatus

If you simply want to modify an existing apparatus, for example to change an algorithm or the default detector configuration, the best approach is to write a new class that inherits from the existing apparatus class.

Note that if you simply want to add a detector to an existing apparatus, you can do so using the "@AddDetector()@":http://hallaweb.jlab.org/podd/html/THaApparatus.html#THaApparatus:AddDetector method (see [[Adding Detectors|adding and removing detectors]]).