refactor: Make seeding config more understandable (#2652)

Re-writing mostly all comments from seeding configuration to make them more understandable.

Core/include/Acts/Seeding/SeedConfirmationRangeConfig.hpp

@@ -15,36 +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 {
-  // z minimum and maximum of middle component of the seed used to define 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
+
+  /// 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 of bottom component of seed that is used to define the number of
-  // compatible top required
+
+  /// 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
 
-  // number of compatible top SPs of seed if bottom 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;
-  // number of compatible top SPs of seed if bottom 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 bottom SP in seed confirmation
+  /// Minimum radius for inner seed component required in quality seed
+  /// confirmation
   float seedConfMinBottomRadius = 60. * Acts::UnitConstants::mm;
-  // maximum zOrigin in seed confirmation
+  /// Maximum longitudinal impact parameter of seed required in quality seed
+  /// confirmation
   float seedConfMaxZOrigin = 150. * Acts::UnitConstants::mm;
-  // minimum impact parameter for 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,55 +16,73 @@
 #include <stdexcept>
 
 namespace Acts {
+
+/// @brief Structure that holds configuration parameters for the seed filter algorithm
 struct SeedFilterConfig {
-  // the allowed delta between two inverted seed radii for them to be considered
-  // compatible.
+  /// Allowed difference in curvature (inverted seed radii) between two
+  /// compatible seeds
   float deltaInvHelixDiameter = 0.00003 * 1. / Acts::UnitConstants::mm;
-  // the transverse impact parameters (d0) is multiplied by this factor and
-  // subtracted from weight
+  /// 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)
+  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)
   float impactWeightFactor = 1.;
-  // the logitudinal impact parameters (z0) is multiplied by this factor and
-  // subtracted from weight
+  /// 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.;
-  // seed weight increased by this value if a compatible seed has been found.
-  float compatSeedWeight = 200.;
-  // minimum distance between compatible seeds to be considered for weight boost
-  float deltaRMin = 5. * Acts::UnitConstants::mm;
-  // 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;
-  // how often do you want to increase the weight of a seed for finding a
-  // compatible seed?
+  /// 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;
-  // Tool to apply experiment specific cuts on collected middle space points
 
-  // 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();
 
-  // seedConfirmation enables seed confirmation cuts - keep seeds if they have
-  // specific values of impact parameter, z-origin and number of compatible
-  // seeds inside a pre-defined range that also depends on the region of the
-  // detector (i.e. forward or central region) defined by SeedConfirmationRange
+  /// Seeding parameters used for quality seed confirmation
+
+  /// 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" seed
+  /// 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;
 
-  // maximum number of lower 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 quality seeds for each middle-bottom SP-dublet in seed
-  // confirmation if the limit is reached we check if there is a lower 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();
 
-  // use deltaR between top and middle SP instead of top radius to search for
-  // compatible SPs
+  /// Other parameters
+
+  /// Use deltaR between top and middle SP instead of top radius to search for
+  /// compatible SPs
   bool useDeltaRorTopRadius = false;
 
   bool isInInternalUnits = false;