HCal Endcap segmentation class is generalized for N-parts endcap

FCCee/ALLEGRO/compact/ALLEGRO_o1_v03/HCalBarrel_TileCal_v03.xml

@@ -46,6 +46,7 @@
   <readouts>
     <readout name="HCalBarrelReadout">
       <segmentation type="FCCSWHCalPhiTheta_k4geo" 
+         detLayout="0"
          offset_z="0"
          width_z="BarHCal_dz*2"
          offset_r="BarHCal_rmin+BarHCal_face_plate_thickness+BarHCal_plate_space"
@@ -59,6 +60,7 @@
     </readout>
     <readout name="HCalBarrelReadoutPhiRow">
       <segmentation type="FCCSWHCalPhiRow_k4geo" 
+         detLayout="0"
          offset_z="0"
          width_z="2795.5*2*mm"
          offset_r="BarHCal_rmin+BarHCal_face_plate_thickness+BarHCal_plate_space"

FCCee/ALLEGRO/compact/ALLEGRO_o1_v03/HCalEndcaps_ThreeParts_TileCal_v03.xml

@@ -45,6 +45,7 @@
     <!-- Default readout of DetailedWedge geometry -->
     <readout name="HCalEndcapReadout">
       <segmentation type="FCCSWHCalPhiTheta_k4geo" 
+         detLayout="1"
          offset_z="HCalEndcap_min_z1+(HCalEndcap_max_z1-HCalEndcap_min_z1)*0.5 HCalEndcap_min_z2+(HCalEndcap_max_z2-HCalEndcap_min_z2)*0.5 HCalEndcap_min_z3+(HCalEndcap_max_z3-HCalEndcap_min_z3)*0.5" 
          width_z="(HCalEndcap_max_z1-HCalEndcap_min_z1) (HCalEndcap_max_z2-HCalEndcap_min_z2) (HCalEndcap_max_z3-HCalEndcap_min_z3)" 
          offset_r="HCalEndcap_inner_radius1+EndcapHCal_face_plate_thickness+EndcapHCal_plate_space HCalEndcap_inner_radius2+EndcapHCal_face_plate_thickness+EndcapHCal_plate_space HCalEndcap_inner_radius3+EndcapHCal_face_plate_thickness+EndcapHCal_plate_space"
@@ -58,6 +59,7 @@
     </readout>
     <readout name="HCalEndcapReadoutPhiRow">
       <segmentation type="FCCSWHCalPhiRow_k4geo" 
+         detLayout="1"
          offset_z="HCalEndcap_min_z1+(HCalEndcap_max_z1-HCalEndcap_min_z1)*0.5 HCalEndcap_min_z2+(HCalEndcap_max_z2-HCalEndcap_min_z2)*0.5 HCalEndcap_min_z3+(HCalEndcap_max_z3-HCalEndcap_min_z3)*0.5" 
          width_z="248.5*2*mm 243.0*2*mm 770.5*2*mm"
          offset_r="HCalEndcap_inner_radius1+EndcapHCal_face_plate_thickness+EndcapHCal_plate_space HCalEndcap_inner_radius2+EndcapHCal_face_plate_thickness+EndcapHCal_plate_space HCalEndcap_inner_radius3+EndcapHCal_face_plate_thickness+EndcapHCal_plate_space"

detectorSegmentations/include/detectorSegmentations/FCCSWHCalPhiRowHandle_k4geo.h

@@ -80,6 +80,9 @@ class FCCSWHCalPhiRow_k4geo : public FCCSWHCalPhiRowHandle_k4geo {
   /// set the coordinate offset in Phi
   inline void setOffsetPhi(double offset) const { access()->implementation->setOffsetPhi(offset); }
 
+  /// set the detector layout
+  inline void setDetLayout(int detLayout) const { access()->implementation->setDetLayout(detLayout); }
+
   /// set the coordinate offset in z-axis
   inline void setOffsetZ(std::vector<double> const&offset) const { access()->implementation->setOffsetZ(offset); }
 
@@ -101,6 +104,9 @@ class FCCSWHCalPhiRow_k4geo : public FCCSWHCalPhiRowHandle_k4geo {
   /// set the grid size in Phi
   inline void setPhiBins(int cellSize) const { access()->implementation->setPhiBins(cellSize); }
 
+  /// access the field name used for layer
+  inline const std::string& fieldNameLayer() const { return access()->implementation->fieldNameLayer(); }
+
   /// access the field name used for theta
   inline const std::string& fieldNameRow() const { return access()->implementation->fieldNameRow(); }
 

detectorSegmentations/include/detectorSegmentations/FCCSWHCalPhiRow_k4geo.h

@@ -11,6 +11,9 @@
  *  Segmentation in row and phi.
  *
  *  Cells are defined in r-z plan by merging the row/sequence of scintillator/absorber.
+ *  Each row consists of 2 * Master_Plate + 1 * Spacer_Plate + 1 * Scintillator.
+ *  Considering a single row as a single cell gives the highest possible granularity.
+ *  More details:  https://indico.cern.ch/event/1475808/contributions/6219554/attachments/2966253/5218774/FCC_FullSim_HCal_slides.pdf
  *
  */
 
@@ -42,13 +45,18 @@ namespace dd4hep {
                         const VolumeID& aVolumeID) const;
 
         /**  Find neighbours of the cell
+        *   Definition of neighbours is explained on slide 7: https://indico.cern.ch/event/1475808/contributions/6219554/attachments/2966253/5218774/FCC_FullSim_HCal_slides.pdf
         *   @param[in] aCellId ID of a cell.
         *   return vector of neighbour cellIDs.
         */
 	std::vector<uint64_t> neighbours(const CellID& cID) const;
 
 
         /**  Calculate layer radii and edges in z-axis.
+        *    Following member variables are calculated:
+        *      m_radii
+        *      m_layerEdges
+        *      m_layerDepth
         */
         void calculateLayerRadii() const;
 
@@ -58,7 +66,9 @@ namespace dd4hep {
         *  In case of a cell with single row/sequence, the index is directly the number of row in the layer.
         *  In case of a cell with several rows/sequences merged, the index is the number of cell in the layer.
         *  For the layers of negative-z Endcap, indexes of cells are negative.
-        *
+        *  Following member variables are calculated:
+        *   m_cellIndexes
+        *   m_cellEdges
         *   @param[in] layer index 
         */
 	void defineCellIndexes(const unsigned int layer) const;
@@ -79,7 +89,7 @@ namespace dd4hep {
         */
         inline int phiBins() const { return m_phiBins; }
 
-        /**  Get the coordinate offset in azimuthal angle.
+        /**  Get the coordinate offset in azimuthal angle, which is the center of cell with m_phiID=0.
         *   return The offset in phi.
         */
         inline double offsetPhi() const { return m_offsetPhi; }
@@ -114,27 +124,34 @@ namespace dd4hep {
         */
         std::vector<std::pair<uint,uint> > getMinMaxLayerId() const ;
 
-        /**  Get the coordinate offset in z-axis.
+        /**  Get the coordinate offset in z-axis. 
+        *   Offset is the middle position of the Barrel or each section of the Endcap.
+        *   For the Barrel, the vector size is 1, while for the Endcap - number of section.
         *   return The offset in z.
         */
         inline std::vector<double> offsetZ() const { return m_offsetZ; }
 
-        /**  Get the z width of the layer.
-        *   return the z width.
+        /**  Get the z length of the layer.
+        *   return the z length.
         */
 	inline std::vector<double> widthZ() const { return m_widthZ; }
 
         /**  Get the coordinate offset in radius.
+        *   Offset is the inner radius of the first layer in the Barrel or in each section of the Endcap.
+        *   For the Barrel, the vector size is 1, while for the Endcap - number of sections.
         *   return the offset in radius.
         */
 	inline std::vector<double> offsetR() const { return m_offsetR; }
 
-        /**  Get the number of layers.
+        /**  Get the number of layers for each different thickness retrieved with dRlayer().
+        *   For the Barrel, the vector size equals to the number of different thicknesses used to form the layers.
+        *   For the Endcap, the vector size equals to the number of sections in the Endcap times the number of different thicknesses used to form the layers.
         *   return the number of layers.
         */
 	inline std::vector<int> numLayers() const { return m_numLayers; }
 
-        /**  Get the dR of layers.
+        /**  Get the dR (thickness) of layers.
+        *   The size of the vector equals to the number of different thicknesses used to form the layers.
         *   return the dR.
         */
 	inline std::vector<double> dRlayer() const { return m_dRlayer; }
@@ -144,6 +161,11 @@ namespace dd4hep {
         */
         inline const std::string& fieldNamePhi() const { return m_phiID; }
 
+        /**  Get the field name for layer.
+        *   return The field name for layer.
+        */
+	inline const std::string& fieldNameLayer() const { return m_layerID; }
+
         /**  Get the field name for row number.
         *   return The field name for row.
         */
@@ -164,6 +186,11 @@ namespace dd4hep {
         */
         inline void setGridSizeRow(std::vector<int> const&size) { m_gridSizeRow = size; }
 
+        /**  Set the detector layout (0 = Barrel; 1 = Endcap).
+        *   @param[in] detLayout
+        */
+	inline void setDetLayout(int detLayout) { m_detLayout = detLayout; }
+
         /**  Set the coordinate offset in z-axis.
         *   @param[in] offset in z (centre of the layer).
         */
@@ -208,12 +235,16 @@ namespace dd4hep {
         double m_offsetPhi;
         /// the field name used for phi
         std::string m_phiID;
+        /// the field name used for layer
+        std::string m_layerID;
         /// the grid size in row for each layer
         std::vector<int> m_gridSizeRow;
         /// dz of row
         double m_dz_row;
         /// the field name used for row
         std::string m_rowID;
+        /// the detector layout (0 = Barrel; 1 = Endcap)
+        int m_detLayout;
         /// the z offset of middle of the layer
         std::vector<double> m_offsetZ;
         /// the z width of the layer

detectorSegmentations/include/detectorSegmentations/FCCSWHCalPhiThetaHandle_k4geo.h

@@ -86,6 +86,9 @@ class FCCSWHCalPhiTheta_k4geo : public FCCSWHCalPhiThetaHandle_k4geo {
   /// set the coordinate offset in Phi
   inline void setOffsetPhi(double offset) const { access()->implementation->setOffsetPhi(offset); }
 
+  /// set the detector layout
+  inline void setDetLayout(int detLayout) const { access()->implementation->setDetLayout(detLayout); }
+
   /// set the coordinate offset in z-axis
   inline void setOffsetZ(std::vector<double> const&offset) const { access()->implementation->setOffsetZ(offset); }
 
@@ -113,6 +116,10 @@ class FCCSWHCalPhiTheta_k4geo : public FCCSWHCalPhiThetaHandle_k4geo {
   /// access the field name used for Phi
   inline const std::string& fieldNamePhi() const { return access()->implementation->fieldNamePhi(); }
 
+  /// access the field name used for layer
+  inline const std::string& fieldNameLayer() const { return access()->implementation->fieldNameLayer(); }
+
+
   /** \brief Returns a std::vector<double> of the cellDimensions of the given cell ID
       in natural order of dimensions (dPhi, dTheta)
 

detectorSegmentations/include/detectorSegmentations/FCCSWHCalPhiTheta_k4geo.h

@@ -10,6 +10,8 @@
  *  Based on GridTheta_k4geo, addition of azimuthal angle coordinate.
  *
  *  Rectangular shape cells are defined in r-z plan and all the hits within a defined cell boundaries are assigned the same cellID.
+ *  Cell borders are defined such that closely follow the theta projective towers.
+ *  More details:  https://indico.cern.ch/event/1475808/contributions/6219554/attachments/2966253/5218774/FCC_FullSim_HCal_slides.pdf
  *
  */
 
@@ -40,13 +42,21 @@ namespace dd4hep {
         virtual CellID cellID(const Vector3D& aLocalPosition, const Vector3D& aGlobalPosition,
                         const VolumeID& aVolumeID) const;
 
-        /**  Find neighbours of the cell
+        /**  Find neighbours of the cell.
+        *   Definition of neighbours is explained on slide 9: https://indico.cern.ch/event/1475808/contributions/6219554/attachments/2966253/5218774/FCC_FullSim_HCal_slides.pdf
         *   @param[in] aCellId ID of a cell.
+        *   @param[in] aDiagonal if true, will include neighbours from diagonal positions in the next and previous layers.
         *   return vector of neighbour cellIDs.
         */
 	std::vector<uint64_t> neighbours(const CellID& cID, bool aDiagonal) const;
 
         /**  Calculate layer radii and edges in z-axis, then define cell edges in each layer using defineCellEdges().
+        *    Following member variables are calculated:
+        *      m_radii
+        *      m_layerEdges
+        *      m_layerDepth
+        *      m_thetaBins (updated through defineCellEdges())
+        *      m_cellEdges (updated through defineCellEdges())
         */
         void defineCellsInRZplan() const;
 
@@ -74,40 +84,47 @@ namespace dd4hep {
         */
         inline int phiBins() const { return m_phiBins; }
 
-        /**  Get the coordinate offset in azimuthal angle.
+        /**  Get the coordinate offset in azimuthal angle, which is the center of cell with m_phiID=0
         *   return The offset in phi.
         */
         inline double offsetPhi() const { return m_offsetPhi; }
 
-        /**  Get the vector of theta bins (cells) in a give layer.
+        /**  Get the vector of theta bins (cells) in a given layer.
         */
 	inline std::vector<int> thetaBins(const uint layer) const {
           if(m_radii.empty()) defineCellsInRZplan();
           if(!m_thetaBins.empty()) return m_thetaBins[layer];
           else return std::vector<int>();
         }
 
-        /**  Get the coordinate offset in z-axis.
+        /**  Get the coordinate offset in z-axis. 
+        *   Offset is the middle position of the Barrel or each section of the Endcap.
+        *   For the Barrel, the vector size is 1, while for the Endcap - number of section.
         *   return The offset in z.
         */
         inline std::vector<double> offsetZ() const { return m_offsetZ; }
 
-        /**  Get the z width of the layer.
-        *   return the z width.
+        /**  Get the z length of the layer.
+        *   return the z length.
         */
 	inline std::vector<double> widthZ() const { return m_widthZ; }
 
         /**  Get the coordinate offset in radius.
+        *   Offset is the inner radius of the first layer in the Barrel or in each section of the Endcap.
+        *   For the Barrel, the vector size is 1, while for the Endcap - number of sections.
         *   return the offset in radius.
         */
 	inline std::vector<double> offsetR() const { return m_offsetR; }
 
-        /**  Get the number of layers.
+        /**  Get the number of layers for each different thickness retrieved with dRlayer().
+        *   For the Barrel, the vector size equals to the number of different thicknesses used to form the layers.
+        *   For the Endcap, the vector size equals to the number of sections in the Endcap times the number of different thicknesses used to form the layers.
         *   return the number of layers.
         */
 	inline std::vector<int> numLayers() const { return m_numLayers; }
 
-        /**  Get the dR of layers.
+        /**  Get the dR (thickness) of layers.
+        *   The size of the vector equals to the number of different thicknesses used to form the layers.
         *   return the dR.
         */
 	inline std::vector<double> dRlayer() const { return m_dRlayer; }
@@ -117,6 +134,11 @@ namespace dd4hep {
         */
         inline const std::string& fieldNamePhi() const { return m_phiID; }
 
+        /**  Get the field name for layer.
+        *   return The field name for layer.
+        */
+        inline const std::string& fieldNameLayer() const { return m_layerID; }
+
         /**  Determine the minimum and maximum polar angle of HCal cell based on the cellID.
         *   @param[in] aCellId ID of a cell.
         *   return Theta.
@@ -138,6 +160,11 @@ namespace dd4hep {
         */
         inline void setOffsetPhi(double offset) { m_offsetPhi = offset; }
 
+        /**  Set the detector layout (0 = Barrel; 1 = Endcap).
+        *   @param[in] detLayout
+        */
+	inline void setDetLayout(int detLayout) { m_detLayout = detLayout; }
+
         /**  Set the coordinate offset in z-axis.
         *   @param[in] offset in z (centre of the layer).
         */
@@ -178,6 +205,10 @@ namespace dd4hep {
         double m_offsetPhi;
         /// the field name used for phi
         std::string m_phiID;
+        /// the field name used for layer
+        std::string m_layerID;
+        /// the detector layout (0 = Barrel; 1 = Endcap)
+        int m_detLayout;
         /// the z offset of middle of the layer
         std::vector<double> m_offsetZ;
         /// the z width of the layer