More comments and removal of unused function

detector/calorimeter/dual-readout-tubes/include/DRTubesconstructor.h

@@ -23,22 +23,45 @@ class DRTubesconstructor {
     // Destructor
     ~DRTubesconstructor() {}
 
+    // Function to calculate some (but not all) tower size parameters
     void calculate_tower_parameters();
+
+    // Function to calculate all parameters which only depend on the tower phi
     void calculate_phi_parameters();
+
+    // Function to calculate all parameters which depend on theta (both tower theta and the theta that has been covered by placing towers)
+    // Since this is different for each tower, this function is called multiple times
     void calculate_theta_parameters();
-    void prepare_tube_volumes();
+
+    // Function to create tube volumes and store the in a map, if they don't already exist
     void assert_tube_existence(int key, bool cher);
+
+    // Function to calculate the width of the support Trap volume at a given y and z
+    // with the option to toggle calculation for the backface or frontface width
     double calculate_trap_width(double given_y, double given_z, bool backface = false);
+    // Same as trap width, but for the tower volume (so dimension of "air" insdie the support structure which is the _trap_ volume)
     double calculate_tower_width(int given_row, bool backface = true);
+
+    // Function to calculate the tube lengths and place them to create the actual tower (not the air)
     void assemble_tower(Volume& tower_air_volume);
+
+    // Mostly just a wrapper function
     void construct_tower_trapezoid(Volume& trap_volume);
+
+    // Function to calculate the position of the tower inside the stave
     void calculate_tower_position();
+
+    // Function to construct the trapezoidal support structure for the tower in which fibres are placed
     void construct_tower(Volume& trap_volume);
+
     void increase_covered_theta(const double& delta_theta) {m_covered_theta += delta_theta;}
+
+    // Function to place the tower in the stave volume
     void place_tower(Volume& stave_volume,
-                        Volume& tower_volume,
-                        unsigned int layer);
+                    Volume& tower_volume,
+                    unsigned int layer);
 
+    // Overarching function to construct the calorimeter
     void construct_calorimeter(Volume& calorimeter_volume);
 
 private:
@@ -75,36 +98,40 @@ class DRTubesconstructor {
     bool m_cher_clad_isSensitive;
     bool m_cher_core_isSensitive;
 
-
+    // Maps to store the tube volumes, so that one volume can be used multiple times
+    // The key to the map is an indicator of the tube length (multiple of the tolerance)
     std::unordered_map<int, Volume> m_scin_tube_volume_map;
     std::unordered_map<int, Volume> m_cher_tube_volume_map;
 
+    // Tolerance for which new tube volumes are created
+    // e.g 1mm, then all tube lengths are rounded (down) to the nearest mm
     double m_tolerance;
 
-    double m_capillary_diameter; // calculated from m_capillary_outer_r
 
     // Constants used through the function (calculated from other parameters)
-    // double m_D; // Long diagonal of hexagaon with capillary_outer_r as inradius
+    double m_capillary_diameter; // calculated from m_capillary_outer_r
     double m_V; // Vertical spacing for pointy top oriented tubes
 
-    // Tower parameters
+    // Tower angle parameters (and derived parameters)
     double m_tower_theta;
     double m_tower_phi;
 
     double m_tower_half_phi;
     double m_tower_tan_half_phi; // calculated from m_tower_phi
     double m_tower_half_length; // calculated from m_calo_inner_r and m_calo_outer_r and m_trap_half_length
+    double m_tower_tan_theta;
 
-    // Tower Phi parameters
+    // Tower size parameters depending on phi
     unsigned int m_num_phi_towers;       // number of towers in phi direction
+    // Tower widths at four edges
     double m_tower_frontface_rightangleedge_x;
     double m_tower_frontface_thetaangleedge_x;
     double m_tower_backface_rightangleedge_x;
     double m_tower_backface_thetaangleedge_x;
+    // Angle between the parallel edges of the front/back face
     double m_angle_edges_x;
 
-    // Tower Theta parameters
-    double m_tower_tan_theta;
+    // Tower size parameters derived from theta
     double m_tower_frontface_y;
     double m_tower_backface_y;
     double m_tower_polar_angle;
@@ -128,11 +155,10 @@ class DRTubesconstructor {
     std::string m_trap_visString;
 
 
-    // Construction parameters
+    // Construction parameters (which change for each tower)
     double m_covered_theta;
     double m_back_shift;
     Position m_tower_position;
-    // Assembly* m_tower_volume;
 
     Material m_air;
     std::string m_air_visString;

detector/calorimeter/dual-readout-tubes/include/DRutils.h

@@ -8,16 +8,20 @@
 
 using namespace dd4hep;
 
+
+// Utility functions for the construction of the barrel dual-readout calorimeter (based on tubes)
 namespace DDDRCaloTubes
 {
+    // Quick rounding functions
     int fast_floor(double x);
     int fast_ceil(double x);
+    // Make sure a given double is an integer (within a tolerance)
     bool check_for_integer(double x);
 
+    // Functions which are used to calculate the tube lengths using the crossing point of a line and a plane
     std::vector<double> get_plane_equation(const Position& point1, const Position& point2, const Position& point3);
     Position get_intersection(const std::vector<double>& plane_coefficients, const Position& line_point, const Direction& line_direction);
     Position get_intersection(const Direction& plane_normal, const Position& plane_point, const Position& line_point, const Direction& line_direction);
-    double distance_from_plane(const std::vector<double>& plane_coefficients, const Position& point);
 } // namespace DDDRCaloTubes
 
 #endif // DRutils_h

detector/calorimeter/dual-readout-tubes/src/DRutils.cpp

@@ -5,6 +5,7 @@ using namespace dd4hep;
 
 namespace DDDRCaloTubes
 {
+    // Fast rounding function which do not do some safety checks the std:: functions provide, since we don't expect problems with the input
     int fast_floor(double x)
     {
         return (int) x - (x < (int) x);
@@ -15,11 +16,13 @@ namespace DDDRCaloTubes
         return (int) x + (x > (int) x);
     }
 
+    // Check if a double is an integer within a certain tolerance
     bool check_for_integer(double x)
     {
         return (std::abs(x - std::round(x)) < 1e-6);
     }
 
+    // Plane equation based on three points on the plane
     std::vector<double> get_plane_equation(const Position& point1, const Position& point2, const Position& point3)
     {
         Direction normal = (point2 - point1).Cross(point3 - point1).Unit();
@@ -31,6 +34,7 @@ namespace DDDRCaloTubes
         return coefficients;
     }
 
+    // Intersection of a line and a plane, based on the plane equation coefficients
     Position get_intersection(const std::vector<double>& plane_coefficients, const Position& line_point, const Direction& line_direction)
     {
         double A = plane_coefficients[0];
@@ -42,20 +46,13 @@ namespace DDDRCaloTubes
         return intersection;
     }
 
+    // Alternative way of getting the intersection of a line and a plane, based on the plane normal and a point on the plane
+    // Used during development for double checking
     Position get_intersection(const Direction& plane_normal, const Position& plane_point, const Position& line_point, const Direction& line_direction)
     {
         double t = (plane_normal.Dot(plane_point - line_point)) / plane_normal.Dot(line_direction);
         Position intersection = line_point + t * line_direction;
         return intersection;
     }
 
-    double distance_from_plane(const std::vector<double>& plane_coefficients, const Position& point)
-    {
-        double A = plane_coefficients[0];
-        double B = plane_coefficients[1];
-        double C = plane_coefficients[2];
-        double D = plane_coefficients[3];
-        return std::abs(A * point.x() + B * point.y() + C * point.z() + D);
-    }
-
 } // namespace DDDRCaloTubes