[Halld-offline] BCAL library

[Mark Ito]

Folks,

I wanted to start looking at photons in the BCAL (actually in general, 
but I started with the BCAL since B comes before F in the alphabet) and 
looking in the library I see a bunch of factories but do not understand 
the relation between them and the objects they produce. I suppose I 
could go through the code, but I thought I would ask the group for 
guidance first.

What I did do was look for comments in the code. I've compiled the ones 
I found in the attached text file. The named files in the list are 
factory header files, but the comment could have come from the .cc file 
or the .h file of either the factory or the object.

My questions, naive ones admittedly:

1. Are these relationships documented somewhere?
2. I vaguely recall janadot showing something like these relationships. 
Does it really? Do we have a recent diagram? Instructions for generating it?
3. I did not look at our Doxygen documentation, since I thought that 
would only show inheritance relations. Should I have looked there?
4. What objects should I use to get photons in the BCAL?

   -- Mark

-------------- next part --------------
DBCALClump_factory.h

  /// This factory creats Clumps based on all DBCALHits. A Clump is an object of
  /// two related clusters between up stream and down stream BCAL Hits. A seed
  /// is found by searching for the highest energy deposited in the hit list that
  /// has both and up stream and down stream value. A list of hits is formed 
  /// around this seed hit independently for up stream and downstream. The hits used
  /// are removed from the search list. From the remaining hit list again the highest
  /// energy deposit is searched that has both an up stream and down stream value and
  /// the procedure is repeated till no hits with both upstream and down stream values
  /// are found. Each seed results in two lists of hits for up and down stream shower
  /// cluster that form a Clump.
  /// Note that at this point a Clump could contain easily two particle showers close 
  /// together. A disentanglement of the Clump will require a successive step.
  /// From a Clump (see DBCALClump.cc) a shower is constructed: verstion 0.1
  /// BTW. Clump is a perfectly good english word ;-)

DBCALCluster_factory.h

DBCALCluster_factory_SINGLE.h

        /// This factory will create a single DBCALCluster objects from
        /// all of the DBCALPoint objects. It is intended only for
        /// debugging of simulated data where a single cluster is expected.
        ///
        /// If there are no DBCALPoint objects, then the DBCALCluster
        /// object is not created.

DBCALGeometry_factory.h

DBCALHit_factory.h

   /// Generate DBCALHit object for each DBCALDigiHit object.
   /// This is where the first set of calibration constants
   /// is applied to convert from digitzed units into natural
   /// units.
   ///
   /// Note that this code does NOT get called for simulated
   /// data in HDDM format. The HDDM event source will copy
   /// the precalibrated values directly into the _data vector.

DBCALPoint_factory.h

/** 
   This object gives a z position to BCAL hits using timing information.
   The z position is relative to the target center because higher objects use 
   the position of hits relative to the target in spherical coordinates.

*/

DBCALShower_factory_CURVATURE.h

// This factory takes showers from the IU shower factory and alters them based on shower
// curvature tables produced by AS.  These can be found in the CCDB under
// BCAL/curvature_central and BCAL/curvature_side.  They give central z-positions of
// energy depositions in the BCAL for each layer based on the reconstructed IU shower's
// energy and theta values.  The two tables are for 'central' sectors and 'side' sectors.
// A central sector (the one or two sectors closest to the centroid of the shower) exhibit
// different deposition ranges in z than a side sector.

// We first grab the IU showers and check for overlap in z.  We want to merge showers that
// are close in z, t, and phi that the IU code may have reconstructed as two separate showers.
// Next, we extract the energies and theta values for each of the IU (and merged) showers.
// Using the curvature tables, we find the appropriate z-bin position for each layer, then
// loop through the points in the event and put any point that falls within the z-bins for a
// shower into that shower.  The z-bin width is determined by the error on the z-positions of
// the depositions and on a set width factor.

// These new colletions of points are then averaged (energy-squared-weighted averages in x, y,
// z, and t) to get the shower values.

DBCALShower_factory.h

DBCALShower_factory_IU.h

DBCALShower_factory_JLAB.h

/// The showers produced here are based on the output of the DBCALClump_factory

DBCALShower_factory_KLOE.h

/// Form fully reconstructed showers from BCAL data based on the KLOE algorithm.
/// The showers produced by this do have calibration applied to correct the
/// output energy based on cluster energy and z-location. This used DBCALHit objects
/// as input. All clustering, merging etc. are done here as described in
/// <A href="http://argus.phys.uregina.ca/cgi-bin/private/DocDB/ShowDocument?docid=569">GlueX-doc-569</A>
///
///  Author's Note: This class started as a functional clone of the default DBCALShower_factory_KLOE --
///  much of the logic and data structure is as written by C. Xu.
///  Revisions were made to get approx 10x speed gain.  The intial version in the repository
///  It has undergone subsequent reision and as of 8-Aug-08 merged back in as the default
///  DBCALShower_factory_KLOE
///

DBCALTDCHit_factory.h

    /// Generate DBCALTDCHit object for each DBCALTDCDigiHit object.
    /// This is where the first set of calibration constants
    /// is applied to convert from digitzed units into natural
    /// units.
    ///
    /// Note that this code does NOT get called for simulated
    /// data in HDDM format. The HDDM event source will copy
    /// the precalibrated values directly into the _data vector.

DBCALUnifiedHit_factory.h

//One DBCALUnifiedHit is created for each DBCALHit. When available, TDC hits
//are also incorporated. The class provides energy in GeV rather than ADC
//units (for now the conversion is just a constant factor) and timewalk
//corrections are also applied. With this class, these corrections only need
//to be applied once.