refactor: Make seeding config more understandable

Core/include/Acts/Seeding/SeedConfirmationRangeConfig.hpp

@@ -15,48 +15,50 @@
 
 namespace Acts {
 
-// defaults experimental cuts to no operation in both seeding algorithms
+/// defaults experimental cuts to no operation in both seeding algorithms
 inline bool noopExperimentCuts(float /*bottomRadius*/, float /*cotTheta*/) {
   return true;
 }
 
-/// @brief contains parameters for  seed confirmation
+/// @brief Contains parameters for quality seed confirmation
+/// @note Requirements on the number of compatible space-points and impact parameters can be defined
+/// for different (r, z) regions of the detector (e.g. forward or central
+/// region) by SeedConfirmationRange. Seeds are classified as "high-quality"
+/// seeds and normal quality seeds. Normal quality seeds are only selected if
+/// no other "high-quality" seed has been found for that inner-middle doublet.
+/// For optimization reasons, the algorithm only calls the seed confirmation
+/// for a certain inner-middle doublet, in case a configurable minimum number
+/// of inner-middle-outer triplets have been found.
 struct SeedConfirmationRangeConfig {
-  // This is used for quality seed confirmation. Where requirements on the
-  // number of compatible space-points and impact parameters can also be defined
-  // for different (r, z) regions of the detector (e.g. forward or central
-  // region) by SeedConfirmationRange. Seeds are classied as "high-quality"
-  // seeds and normal quality seeds. Normal quality seeds are only selected if
-  // no other "high-quality" seeds has been found for that inner-middle doublet.
-  // For optimization reasons, the algorithm only calls the seed confirmation
-  // for a certain inner-middle doublet in case a configurable minimum number of
-  // inner-middle-outer triplets have been found.
-
-  // Minimum and maximum z position of middle component of the seed used to
-  // split the region of the detector for seed confirmation
+  /// Minimum z position of middle component of the seed used to
+  /// split the region of the detector for seed confirmation
   float zMinSeedConf =
       std::numeric_limits<float>::lowest();  // Acts::UnitConstants::mm
-  float zMaxSeedConf = std::numeric_limits<
-      float>::max();  // Acts::UnitConstants::mm
-                      // Radius position of inner seed component that is used to
-                      // split the region of the detector for seed confirmation
+
+  /// Maximum z position of middle component of the seed used to
+  /// split the region of the detector for seed confirmation
+  float zMaxSeedConf =
+      std::numeric_limits<float>::max();  // Acts::UnitConstants::mm
+
+  /// Radius position of inner seed component that is used to
+  /// split the region of the detector for seed confirmation
   float rMaxSeedConf =
       std::numeric_limits<float>::max();  // Acts::UnitConstants::mm
 
-  // Minimum number of compatible outer space-points required in quality seed
-  // confirmation if inner space-points radius is larger than rMaxSeedConf
+  /// Minimum number of compatible outer space-points required in quality seed
+  /// confirmation if inner space-points radius is larger than rMaxSeedConf
   std::size_t nTopForLargeR = 0;
-  // Minimum number of compatible outer space-points required in quality seed
-  // confirmation if inner space-points radius is smaller than rMaxSeedConf
+  /// Minimum number of compatible outer space-points required in quality seed
+  /// confirmation if inner space-points radius is smaller than rMaxSeedConf
   std::size_t nTopForSmallR = 0;
 
-  // Minimum radius for inner seed component required in quality in seed
-  // confirmation
+  /// Minimum radius for inner seed component required in quality in seed
+  /// confirmation
   float seedConfMinBottomRadius = 60. * Acts::UnitConstants::mm;
-  // Maximum longitudinal impact parameter of seed required in quality seed
-  // confirmation
+  /// Maximum longitudinal impact parameter of seed required in quality seed
+  /// confirmation
   float seedConfMaxZOrigin = 150. * Acts::UnitConstants::mm;
-  // Minimum impact parameter of seed required in quality seed confirmation
+  /// Minimum impact parameter of seed required in quality seed confirmation
   float minImpactSeedConf = 1. * Acts::UnitConstants::mm;
 };
 

Core/include/Acts/Seeding/SeedFilterConfig.hpp

@@ -16,75 +16,73 @@
 #include <stdexcept>
 
 namespace Acts {
+
+/// @brief Structure that holds configuration parameters for the seed filter algorithm
 struct SeedFilterConfig {
-  // Allowed difference in curvature (inverted seed radii) between two
-  // compatible seeds
+  /// Allowed difference in curvature (inverted seed radii) between two
+  /// compatible seeds
   float deltaInvHelixDiameter = 0.00003 * 1. / Acts::UnitConstants::mm;
-  // Minimum distance between compatible outer space-points to be considered.
-  // This is used to avoid counting space-points from the same layer
+  /// Minimum distance between compatible outer space-points to be considered.
+  /// This is used to avoid counting space-points from the same layer
   float deltaRMin = 5. * Acts::UnitConstants::mm;
-  // Seed weight/score is increased by this value if a compatible seed has been
-  // found. This is the c1 factor in the seed score calculation (w = c1 * Nt -
-  // c2 * d0 - c3 * z0)
+  /// Seed weight/score is increased by this value if a compatible seed has been
+  /// found. This is the c1 factor in the seed score calculation (w = c1 * Nt -
+  /// c2 * d0 - c3 * z0)
   float compatSeedWeight = 200.;
-  // The transverse impact parameters (d0) is multiplied by this factor and
-  // subtracted from weight. This is the c2 factor in the seed score calculation
-  // (w = c1 * Nt - c2 * d0 - c3 * z0)
+  /// The transverse impact parameters (d0) is multiplied by this factor and
+  /// subtracted from weight. This is the c2 factor in the seed score
+  /// calculation (w = c1 * Nt - c2 * d0 - c3 * z0)
   float impactWeightFactor = 1.;
-  // The logitudinal impact parameters (z0) is multiplied by this factor and
-  // subtracted from weight. This is the c3 factor in the seed score calculation
-  // (w = c1 * Nt - c2 * d0 - c3 * z0)
+  /// The logitudinal impact parameters (z0) is multiplied by this factor and
+  /// subtracted from weight. This is the c3 factor in the seed score
+  /// calculation (w = c1 * Nt - c2 * d0 - c3 * z0)
   float zOriginWeightFactor = 1.;
-  // Maximum number (minus one) of accepted seeds per middle space-point
-  // In dense environments many seeds may be found per middle space-point
-  // Only seeds with the highest weight will be kept if this limit is reached
+  /// Maximum number (minus one) of accepted seeds per middle space-point
+  /// In dense environments many seeds may be found per middle space-point
+  /// Only seeds with the highest weight will be kept if this limit is reached
   unsigned int maxSeedsPerSpM = 10;
-  // Maximum limit to number of compatible space-point used in score
-  // calculation. We increase by c1 the weight calculation for each compatible
-  // space-point until we reach compatSeedLimit
+  /// Maximum limit to number of compatible space-point used in score
+  /// calculation. We increase by c1 the weight calculation for each compatible
+  /// space-point until we reach compatSeedLimit
   std::size_t compatSeedLimit = 2;
 
-  // Increment in seed weight if the number of compatible seeds is larger than
-  // numSeedIncrement, this is used in case of high occupancy scenarios if we
-  // want to increase the weight of the seed by seedWeightIncrement when the
-  // number of compatible seeds is higher than a certain value
+  /// Increment in seed weight if the number of compatible seeds is larger than
+  /// numSeedIncrement, this is used in case of high occupancy scenarios if we
+  /// want to increase the weight of the seed by seedWeightIncrement when the
+  /// number of compatible seeds is higher than a certain value
   float seedWeightIncrement = 0;
   float numSeedIncrement = std::numeric_limits<float>::infinity();
 
-  /*
-   * Seeding parameters used for quality seed confirmation
-   */
+  /// Seeding parameters used for quality seed confirmation
 
-  // Enable quality seed confirmation, this is different than default seeding
-  // confiramtion because it can also be defined for different (r, z) regions of
-  // the detector (e.g. forward or central region) by SeedConfirmationRange.
-  // Seeds are classied as "high-quality" seeds and normal quality seeds. Normal
-  // quality seeds are only selected if no other "high-quality" seeds has been
-  // found for that inner-middle doublet.
+  /// Enable quality seed confirmation, this is different than default seeding
+  /// confirmation because it can also be defined for different (r, z) regions
+  /// of the detector (e.g. forward or central region) by SeedConfirmationRange.
+  /// Seeds are classified as "high-quality" seeds and normal quality seeds.
+  /// Normal quality seeds are only selected if no other "high-quality" seeds
+  /// has been found for that inner-middle doublet.
   bool seedConfirmation = false;
-  // Contains parameters for central seed confirmation
+  /// Contains parameters for central seed confirmation
   SeedConfirmationRangeConfig centralSeedConfirmationRange;
-  // Contains parameters for forward seed confirmation
+  /// Contains parameters for forward seed confirmation
   SeedConfirmationRangeConfig forwardSeedConfirmationRange;
 
-  // If seedConfirmation is true we classify seeds as "high-quality" seeds.
-  // Seeds that are not confirmed as "high-quality" are only selected if no
-  // other "high-quality" seeds has been found for that inner-middle doublet
-  // Maximum number of normal seeds (not classied as "high-quality" seeds) in
-  // seed confirmation
+  /// If seedConfirmation is true we classify seeds as "high-quality" seeds.
+  /// Seeds that are not confirmed as "high-quality" are only selected if no
+  /// other "high-quality" seed has been found for that inner-middle doublet
+  /// Maximum number of normal seeds (not classified as "high-quality" seeds)
+  /// in seed confirmation
   std::size_t maxSeedsPerSpMConf = std::numeric_limits<std::size_t>::max();
-  // Maximum number of "high-quality" seeds for each inner-middle SP-dublet in
-  // seed confirmation. If the limit is reached we check if there is a normal
-  // quality seed to be replaced
+  /// Maximum number of "high-quality" seeds for each inner-middle SP-dublet in
+  /// seed confirmation. If the limit is reached we check if there is a normal
+  /// quality seed to be replaced
   std::size_t maxQualitySeedsPerSpMConf =
       std::numeric_limits<std::size_t>::max();
 
-  /*
-   * Other parameters
-   */
+  /// Other parameters
 
-  // Use deltaR between top and middle SP instead of top radius to search for
-  // compatible SPs
+  /// Use deltaR between top and middle SP instead of top radius to search for
+  /// compatible SPs
   bool useDeltaRorTopRadius = false;
 
   bool isInInternalUnits = false;