include/LCClustering/ConeClusteringAlgorithm.h

0001 /**
0002  *  @file   LCContent/include/LCClustering/ConeClusteringAlgorithm.h
0003  *
0004  *  @brief  Header file for the clustering algorithm class.
0005  *
0006  *  $Log: $
0007  */
0008 #ifndef LC_CONE_CLUSTERING_ALGORITHM_H
0009 #define LC_CONE_CLUSTERING_ALGORITHM_H 1
0010
0011 #include "Pandora/Algorithm.h"
0012
0013 #include "Helpers/ClusterFitHelper.h"
0014
0015 #include "Objects/CaloHit.h"
0016 #include "Objects/CartesianVector.h"
0017
0018 #include "LCUtility/KDTreeLinkerAlgoT.h"
0019
0020 #include <unordered_map>
0021
0022 namespace lc_content {
0023
0024 /**
0025  *  @brief  ConeClusteringAlgorithm class
0026  */
0027 class ConeClusteringAlgorithm : public pandora::Algorithm {
0028 public:
0029   /**
0030    *  @brief Default constructor
0031    */
0032   ConeClusteringAlgorithm();
0033
0034 private:
0035   pandora::StatusCode Run();
0036   pandora::StatusCode ReadSettings(const pandora::TiXmlHandle xmlHandle);
0037
0038   /**
0039    *  @brief  Fill the kd-trees we will use to do fast lookups of clusters
0040    *
0041    *  @param  none, just internal initialization
0042    */
0043   pandora::StatusCode InitializeKDTrees(const pandora::TrackList*, const pandora::CaloHitList*);
0044
0045   /**
0046    *  @brief  Use current track list to make seed clusters
0047    *
0048    *  @param  pTrackList address of the track list
0049    *  @param  clusterVector to receive the addresses of clusters created (which could also be accessed via current
0050    * cluster list)
0051    */
0052   pandora::StatusCode SeedClustersWithTracks(const pandora::TrackList* const pTrackList,
0053                                              pandora::ClusterVector& clusterVector);
0054
0055   typedef std::unordered_map<const pandora::Cluster*, const pandora::ClusterFitResult> ClusterFitResultMap;
0056   typedef KDTreeLinkerAlgo<const pandora::CaloHit*, 4> HitKDTree;
0057   typedef KDTreeNodeInfoT<const pandora::CaloHit*, 4> HitKDNode;
0058   typedef KDTreeLinkerAlgo<const pandora::Track*, 3> TrackKDTree;
0059   typedef KDTreeNodeInfoT<const pandora::Track*, 3> TrackKDNode;
0060
0061   /**
0062    *  @brief  Update the properties of the current clusters, calculating their current directions and storing the fit
0063    * results in a provided map
0064    *
0065    *  @param  clusterVector vector containing addresses of current clusters
0066    *  @param  clusterFitResultMap to receive the populated cluster fit result map
0067    */
0068   pandora::StatusCode GetCurrentClusterFitResults(const pandora::ClusterVector& clusterVector,
0069                                                   ClusterFitResultMap& clusterFitResultMap) const;
0070
0071   /**
0072    *  @brief  Match clusters to calo hits in previous pseudo layers
0073    *
0074    *  @param  pseudoLayer the current pseudo layer
0075    *  @param  relevantCaloHits the calo hits in the current pseudo layer
0076    *  @param  clusterFitResultMap containing the current cluster fit results
0077    *  @param  clusterVector vector containing addresses of current clusters
0078    */
0079   pandora::StatusCode FindHitsInPreviousLayers(unsigned int pseudoLayer, const pandora::CaloHitVector& relevantCaloHits,
0080                                                const ClusterFitResultMap& clusterFitResultMap,
0081                                                pandora::ClusterVector& clusterVector);
0082
0083   /**
0084    *  @brief  Match clusters to calo hits in current pseudo layer
0085    *
0086    *  @param  pseudoLayer the current pseudo layer
0087    *  @param  relevantCaloHits the calo hits in the current pseudo layer
0088    *  @param  clusterFitResultMap containing the current cluster fit results
0089    *  @param  clusterVector vector containing addresses of current clusters
0090    */
0091   pandora::StatusCode FindHitsInSameLayer(unsigned int pseudoLayer, const pandora::CaloHitVector& relevantCaloHits,
0092                                           const ClusterFitResultMap& clusterFitResultMap,
0093                                           pandora::ClusterVector& clusterVector);
0094
0095   /**
0096    *  @brief  Get the "generic distance" between a calo hit and a cluster; the smaller the distance, the stronger the
0097    * association
0098    *
0099    *  @param  pCluster address of the cluster
0100    *  @param  pCaloHit address of the calo hit
0101    *  @param  searchLayer the pseudolayer currently being examined
0102    *  @param  clusterFitResultMap containing the current cluster fit results
0103    *  @param  genericDistance to receive the generic distance
0104    */
0105   pandora::StatusCode GetGenericDistanceToHit(const pandora::Cluster* const pCluster,
0106                                               const pandora::CaloHit* const pCaloHit, const unsigned int searchLayer,
0107                                               const ClusterFitResultMap& clusterFitResultMap,
0108                                               float& genericDistance) const;
0109
0110   /**
0111    *  @brief  Get the generic distance between a calo hit and a cluster in the same pseudo layer
0112    *
0113    *  @param  pCaloHit address of the calo hit
0114    *  @param  pCaloHitList address of the cluster's constituent hit list
0115    *  @param  distance to receive the distance
0116    */
0117   pandora::StatusCode GetDistanceToHitInSameLayer(const pandora::CaloHit* const pCaloHit,
0118                                                   const pandora::CaloHitList* const pCaloHitList,
0119                                                   float& distance) const;
0120
0121   /**
0122    *  @brief  Get the smallest cone approach distance between a calo hit and all the hits in a cluster, using a
0123    * specified measurement of the cluster direction
0124    *
0125    *  @param  pCaloHit address of the calo hit
0126    *  @param  pCaloHitList
0127    *  @param  clusterDirection
0128    *  @param  distance to receive the generic distance
0129    */
0130   pandora::StatusCode GetConeApproachDistanceToHit(const pandora::CaloHit* const pCaloHit,
0131                                                    const pandora::CaloHitList* const pCaloHitList,
0132                                                    const pandora::CartesianVector& clusterDirection,
0133                                                    float& distance) const;
0134
0135   /**
0136    *  @brief  Get the cone approach distance between a calo hit and a specified point in the cluster, using a specified
0137    *          measurement of the cluster direction
0138    *
0139    *  @param  pCaloHit address of the calo hit
0140    *  @param  clusterPosition the cluster position vector
0141    *  @param  clusterDirection the cluster direction unit vector
0142    *  @param  distance to receive the distance
0143    */
0144   pandora::StatusCode GetConeApproachDistanceToHit(const pandora::CaloHit* const pCaloHit,
0145                                                    const pandora::CartesianVector& clusterPosition,
0146                                                    const pandora::CartesianVector& clusterDirection,
0147                                                    float& distance) const;
0148
0149   /**
0150    *  @brief  Get the distance between a calo hit and the track seed (projected) position at the calorimeter surface,
0151    * ONLY calculated if: 1) the calo hit is within the first m_maxLayersToTrackSeed OR 2) cluster contains a hit
0152    * consistent with the track seed within the last m_maxLayersToTrackLikeHit
0153    *
0154    *  @param  pCluster address of the cluster
0155    *  @param  pCaloHit address of the calo hit
0156    *  @param  the pseudolayer currently being examined
0157    *  @param  to receive the distance
0158    */
0159   pandora::StatusCode GetDistanceToTrackSeed(const pandora::Cluster* const pCluster,
0160                                              const pandora::CaloHit* const pCaloHit, unsigned int searchLayer,
0161                                              float& distance) const;
0162
0163   /**
0164    *  @brief  Get the distance between a calo hit and the track seed (projected) position at the calorimeter surface
0165    *
0166    *  @param  pCluster address of the cluster
0167    *  @param  pCaloHit address of the calo hit
0168    *  @param  distance to receive the distance
0169    */
0170   pandora::StatusCode GetDistanceToTrackSeed(const pandora::Cluster* const pCluster,
0171                                              const pandora::CaloHit* const pCaloHit, float& distance) const;
0172
0173   /**
0174    *  @brief  Remove any empty clusters at the end of the algorithm
0175    *
0176    *  @param  clusterVector containing the addresses of all clusters created
0177    */
0178   pandora::StatusCode RemoveEmptyClusters(const pandora::ClusterVector& clusterVector) const;
0179
0180   /**
0181    *  @brief  kd-tree containing all tracks in given to the clusterizer
0182    */
0183   std::vector<TrackKDNode> m_trackNodes;
0184   TrackKDTree m_tracksKdTree;
0185
0186   /**
0187    *  @brief  kd-tree containing all rechits given to the clusterizer
0188    */
0189   std::vector<HitKDNode> m_hitNodes;
0190   HitKDTree m_hitsKdTree;
0191
0192   /**
0193    *  @brief  hashtable to look up hits in clusters
0194    */
0195   std::unordered_map<const pandora::CaloHit*, const pandora::Cluster*> m_hitsToClusters;
0196
0197   /**
0198    *  @brief  hashtable to look up hits in clusters
0199    */
0200   std::unordered_map<const pandora::Track*, const pandora::Cluster*> m_tracksToClusters;
0201
0202   unsigned int m_clusterSeedStrategy; ///< Flag determining if and how clusters should be seeded with tracks
0203
0204   bool m_shouldUseOnlyECalHits; ///< Whether to only use ecal hits in the clustering algorithm
0205   bool m_shouldUseIsolatedHits; ///< Whether to use isolated hits in the clustering algorithm
0206
0207   unsigned int
0208       m_layersToStepBackFine; ///< Number of layers to step back when associating a fine granularity hit to clusters
0209   unsigned int
0210       m_layersToStepBackCoarse; ///< Number of layers to step back when associating a coarse granularity hit to clusters
0211
0212   unsigned int m_clusterFormationStrategy; ///< Flag determining when to add "best" calo hit found to clusters
0213   float m_genericDistanceCut;              ///< Generic distance cut to apply throughout algorithm
0214
0215   float m_minHitTrackCosAngle;   ///< Min cos(angle) between calo hit position and track projection
0216   float m_minHitClusterCosAngle; ///< Min cos(angle) between calo hit position and cluster searchlayer centroid
0217
0218   bool m_shouldUseTrackSeed;           ///< Whether to use track seed information in clustering
0219   unsigned int m_trackSeedCutOffLayer; ///< Pseudo layer beyond which track seed is no longer considered
0220   bool m_shouldFollowInitialDirection; ///< Whether the cluster should grow preferentially in its initial direction
0221
0222   float m_sameLayerPadWidthsFine;   ///< Fine adjacent pad widths used to calculate generic distance to same layer hit
0223   float m_sameLayerPadWidthsCoarse; ///< Coarse adjacent pad widths used to calculate generic distance to same layer hit
0224
0225   float m_coneApproachMaxSeparation2; ///< Maximum separation between calo hit and specified cluster position (squared)
0226   float m_tanConeAngleFine;           ///< Fine tan cone angle used to calculate cone approach distance
0227   float m_tanConeAngleCoarse;         ///< Coarse tan cone angle used to calculate cone approach distance
0228   float m_additionalPadWidthsFine;    ///< Fine adjacent pad widths used to calculate cone approach distance
0229   float m_additionalPadWidthsCoarse;  ///< Coarse adjacent pad widths used to calculate cone approach distance
0230   float
0231       m_maxClusterDirProjection; ///< Max projection of cluster-hit separation in cluster dir to calculate cone distance
0232   float
0233       m_minClusterDirProjection; ///< Min projection of cluster-hit separation in cluster dir to calculate cone distance
0234
0235   float m_trackPathWidth;          ///< Track path width, used to determine whether hits are associated with seed track
0236   float m_maxTrackSeedSeparation2; ///< Maximum distance between a calo hit and track seed (squared)
0237
0238   unsigned int
0239       m_maxLayersToTrackSeed; ///< Max number of layers to the track seed for trackSeedDistance to be calculated
0240   unsigned int
0241       m_maxLayersToTrackLikeHit; ///< Max number of layers to a "track-like" hit for trackSeedDistance to be calculated
0242
0243   unsigned int
0244       m_nLayersSpannedForFit; ///< Min number of layers spanned by cluster before current direction fit is performed
0245   unsigned int m_nLayersSpannedForApproxFit; ///< If current fit fails, but cluster spans enough layers, calculate an
0246                                              ///< approximate fit
0247   unsigned int m_nLayersToFit;   ///< Number of layers (from outermost layer) to examine in current direction fit
0248   float m_nLayersToFitLowMipCut; ///< Low cluster mip fraction threshold, below which may need to fit more layers
0249   unsigned int m_nLayersToFitLowMipMultiplier; ///< Number of layers to fit multiplier for low mip fraction clusters
0250
0251   float m_fitSuccessDotProductCut1; ///< 1. Min value of dot product (current fit dir dot initial dir) for fit success
0252   float m_fitSuccessChi2Cut1;       ///< 1. Max value of fit chi2 for fit success
0253
0254   float m_fitSuccessDotProductCut2; ///< 2. Min value of dot product (current fit dir dot initial dir) for fit success
0255   float m_fitSuccessChi2Cut2;       ///< 2. Max value of fit chi2 for fit success
0256
0257   float m_mipTrackChi2Cut; ///< Max value of fit chi2 for track seeded cluster to retain its IsMipTrack status
0258
0259   unsigned int m_firstLayer; ///< cache the pseudo layer at IP
0260 };
0261
0262 } // namespace lc_content
0263
0264 #endif // #ifndef LC_CONE_CLUSTERING_ALGORITHM_H