Merge branch 'main' into clang-format

AJPfleger · Nov 7, 2023 · b253a52 · b253a52
2 parents e4e4c3d + 7925974
commit b253a52
Show file tree

Hide file tree

Showing 186 changed files with 1,113 additions and 1,762 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -15,21 +15,43 @@ concurrency:
 jobs:
   docs:
     runs-on: ubuntu-latest
-    container: ghcr.io/acts-project/ubuntu2204:v41
     env:
         DOXYGEN_WARN_AS_ERROR: FAIL_ON_WARNINGS
+        DOXYGEN_VERSION: 1.9.4
     steps:
       - uses: actions/checkout@v3
+
+      - name: Cache doxygen
+        id: cache-doxygen
+        uses: actions/cache@v3
+        with:
+          path: /usr/local/bin/doxygen
+          key: doxygen_${{ env.DOXYGEN_VERSION }}
+
+      - name: Install doxygen
+        if: steps.cache-doxygen.outputs.cache-hit != 'true'
+        run: >
+          curl -SL https://sourceforge.net/projects/doxygen/files/rel-${{ env.DOXYGEN_VERSION }}/doxygen-${{ env.DOXYGEN_VERSION }}.linux.bin.tar.gz/download | tar -xzC .
+          && mv doxygen-${{ env.DOXYGEN_VERSION }}/bin/doxygen /usr/local/bin/doxygen
+
       - name: Install dependencies
         run: >
-          curl -SL https://sourceforge.net/projects/doxygen/files/rel-1.9.4/doxygen-1.9.4.linux.bin.tar.gz/download | tar -xzC .
-          && mv doxygen-1.9.4/bin/doxygen /usr/local/bin/doxygen
-          && pip3 install --upgrade pip
+          pip3 install --upgrade pip
           && pip install -r docs/requirements.txt
-      - name: Configure
-        run: cmake -B build -S . -GNinja -DACTS_BUILD_DOCS=ON
-      - name: Build
-        run: cmake --build build --target docs-with-api
+
+      - name: Build documentation
+        run: >
+          cd docs
+          && sphinx-build
+          -b html
+          -d _build/doctrees/
+          -j auto
+          -W
+          --keep-going
+          -t run_doxygen
+          -b linkcheck
+          . _build/html/
+
       - uses: actions/upload-artifact@v3
         with:
           name: acts-docs

diff --git a/Core/include/Acts/Definitions/Algebra.hpp b/Core/include/Acts/Definitions/Algebra.hpp
@@ -42,7 +42,6 @@ namespace Acts {
 /// no dynamic-sized symmetric matrix type is defined. Use the
 /// `ActsDynamicMatrix` instead.
 ///
-/// @{
 
 /// Common scalar (floating point type used for the default algebra types.
 ///
@@ -67,15 +66,12 @@ using ActsDynamicVector = Eigen::Matrix<ActsScalar, Eigen::Dynamic, 1>;
 using ActsDynamicMatrix =
     Eigen::Matrix<ActsScalar, Eigen::Dynamic, Eigen::Dynamic>;
 
-/// @}
-
 /// @defgroup coordinates-types Fixed-size vector/matrix types for coordinates
 ///
 /// These predefined types should always be used when handling coordinate
 /// vectors in different coordinate systems, i.e. on surfaces (2d), spatial
 /// position (3d), or space-time (4d).
 ///
-/// @{
 
 // coordinate vectors
 using Vector2 = ActsVector<2>;
@@ -104,6 +100,4 @@ using AngleAxis3 = Eigen::AngleAxis<ActsScalar>;
 using Transform2 = Eigen::Transform<ActsScalar, 2, Eigen::AffineCompact>;
 using Transform3 = Eigen::Transform<ActsScalar, 3, Eigen::Affine>;
 
-/// @}
-
 }  // namespace Acts
diff --git a/Core/include/Acts/Propagator/AbortList.hpp b/Core/include/Acts/Propagator/AbortList.hpp
@@ -20,8 +20,6 @@ namespace hana = boost::hana;
 
 namespace Acts {
 
-/// @cond
-
 /// @brief AbortList object to be used in the propagation
 ///
 /// The abort list is a list of structs or classes that
@@ -39,10 +37,12 @@ struct AbortList : public detail::Extendable<aborters_t...> {
   using detail::Extendable<aborters_t...>::tuple;
 
  public:
+  /// @cond
   // This uses the type collector
   using result_type = typename decltype(hana::unpack(
       detail::type_collector_t<detail::action_type_extractor, aborters_t...>,
       hana::template_<AbortList>))::type;
+  /// @endcond
 
   using detail::Extendable<aborters_t...>::get;
 
@@ -103,6 +103,7 @@ struct AbortList : public detail::Extendable<aborters_t...> {
   /// @param [in] stepper Stepper used for the propagation
   /// @param [in] navigator Navigator used for the propagation
   /// @param [in] result is the result object from a certain action
+  /// @param [in] args are the arguments to be passed to the aborters
   template <typename propagator_state_t, typename stepper_t,
             typename navigator_t, typename result_t, typename... Args>
   bool operator()(propagator_state_t& state, const stepper_t& stepper,
@@ -114,6 +115,4 @@ struct AbortList : public detail::Extendable<aborters_t...> {
   }
 };
 
-/// @endcond
-
 }  // namespace Acts
diff --git a/Core/include/Acts/Propagator/ActionList.hpp b/Core/include/Acts/Propagator/ActionList.hpp
@@ -21,8 +21,6 @@ namespace hana = boost::hana;
 
 namespace Acts {
 
-/// @cond
-
 /// @brief ActionList implementation to be used with the propagator
 ///
 /// This is the ActionList struct that is used in the propagator
@@ -37,11 +35,13 @@ struct ActionList : public detail::Extendable<actors_t...> {
   using detail::Extendable<actors_t...>::tuple;
 
  public:
+  /// @cond
   // This uses the type collector and unpacks using the `R` meta function
   template <template <typename...> class R>
   using result_type = typename decltype(hana::unpack(
       detail::type_collector_t<detail::result_type_extractor, actors_t...>,
       hana::template_<R>))::type;
+  /// @endcond
 
   using detail::Extendable<actors_t...>::get;
 
@@ -82,6 +82,7 @@ struct ActionList : public detail::Extendable<actors_t...> {
   /// @param [in] stepper The stepper in use
   /// @param [in] navigator The navigator in use
   /// @param [in,out] result This is the result object from actions
+  /// @param [in] args The arguments to be passed to the actions
   template <typename propagator_state_t, typename stepper_t,
             typename navigator_t, typename result_t, typename... Args>
   void operator()(propagator_state_t& state, const stepper_t& stepper,
@@ -93,6 +94,4 @@ struct ActionList : public detail::Extendable<actors_t...> {
   }
 };
 
-/// @endcond
-
 }  // namespace Acts
diff --git a/Core/include/Acts/Propagator/ConstrainedStep.hpp b/Core/include/Acts/Propagator/ConstrainedStep.hpp
@@ -97,8 +97,6 @@ class ConstrainedStep {
   constexpr Scalar value(Type type) const { return m_values[type]; }
 
   /// Access the accuracy value
-  ///
-  /// @param type is the requested parameter type
   constexpr Scalar accuracy() const { return m_accuracy; }
 
   /// release a certain constraint value
@@ -107,8 +105,6 @@ class ConstrainedStep {
   constexpr void release(Type type) { m_values[type] = kNotSet; }
 
   /// release accuracy
-  ///
-  /// @param type is the constraint type to be released
   constexpr void releaseAccuracy() { m_accuracy = kNotSet; }
 
   /// Update the step size of a certain type

diff --git a/Core/include/Acts/Propagator/Propagator.hpp b/Core/include/Acts/Propagator/Propagator.hpp
@@ -32,6 +32,15 @@
 
 namespace Acts {
 
+/// @brief Different stages during propagation
+enum class PropagatorStage {
+  invalid,          ///< Invalid stage
+  prePropagation,   ///< Before the propagation
+  postPropagation,  ///< After the propagation
+  preStep,          ///< Before a step
+  postStep,         ///< After a step
+};
+
 /// @brief Simple class holding result of propagation call
 ///
 /// @tparam parameters_t Type of final track parameters
@@ -270,6 +279,9 @@ class Propagator final {
           navigation{std::move(navigationIn)},
           geoContext(topts.geoContext) {}
 
+    /// Propagation stage
+    PropagatorStage stage = PropagatorStage::invalid;
+
     /// These are the options - provided for each propagation step
     propagator_options_t options;
 

diff --git a/Core/include/Acts/Propagator/Propagator.ipp b/Core/include/Acts/Propagator/Propagator.ipp
@@ -20,6 +20,8 @@ auto Acts::Propagator<S, N>::propagate_impl(propagator_state_t& state,
   // Pre-stepping call to the navigator and action list
   ACTS_VERBOSE("Entering propagation.");
 
+  state.stage = PropagatorStage::prePropagation;
+
   // Navigator initialize state call
   m_navigator.initialize(state, m_stepper);
   // Pre-Stepping call to the action list
@@ -41,6 +43,7 @@ auto Acts::Propagator<S, N>::propagate_impl(propagator_state_t& state,
     // Propagation loop : stepping
     for (; result.steps < state.options.maxSteps; ++result.steps) {
       // Pre-Stepping: target setting
+      state.stage = PropagatorStage::preStep;
       m_navigator.preStep(state, m_stepper);
       // Perform a propagation step - it takes the propagation state
       Result<double> res = m_stepper.step(state, m_navigator);
@@ -57,6 +60,7 @@ auto Acts::Propagator<S, N>::propagate_impl(propagator_state_t& state,
       }
       // Post-stepping:
       // navigator post step call - action list - aborter list
+      state.stage = PropagatorStage::postStep;
       m_navigator.postStep(state, m_stepper);
       state.options.actionList(state, m_stepper, m_navigator, result, logger());
       if (state.options.abortList(state, m_stepper, m_navigator, result,
@@ -69,6 +73,8 @@ auto Acts::Propagator<S, N>::propagate_impl(propagator_state_t& state,
     ACTS_VERBOSE("Propagation terminated without going into stepping loop.");
   }
 
+  state.stage = PropagatorStage::postPropagation;
+
   // if we didn't terminate normally (via aborters) set navigation break.
   // this will trigger error output in the lines below
   if (!terminatedNormally) {

diff --git a/Core/include/Acts/Surfaces/ConeBounds.hpp b/Core/include/Acts/Surfaces/ConeBounds.hpp
@@ -31,7 +31,7 @@ namespace Acts {
 ///  The cone can open to both sides, steered by \f$ z_min \f$ and \f$ z_max
 ///  \f$.
 ///
-///  @image html figures/ConeBounds.gif
+///  @image html ConeBounds.gif
 ///
 
 class ConeBounds : public SurfaceBounds {

diff --git a/Core/include/Acts/Surfaces/CylinderBounds.hpp b/Core/include/Acts/Surfaces/CylinderBounds.hpp
@@ -24,6 +24,7 @@
 namespace Acts {
 
 /// @class CylinderBounds
+/// @image html CylinderBounds.gif
 ///
 /// Bounds for a cylindrical Surface.
 ///

diff --git a/Core/include/Acts/Surfaces/CylinderSurface.hpp b/Core/include/Acts/Surfaces/CylinderSurface.hpp
@@ -38,7 +38,7 @@ class DetectorElementBase;
 /// since it builds the surfaces of all TrackingVolumes at container level
 /// for a cylindrical tracking geometry.
 ///
-/// @image html figures/CylinderSurface.png
+/// @image html CylinderSurface.png
 
 class CylinderSurface : public Surface {
 #ifndef DOXYGEN

diff --git a/Core/include/Acts/Surfaces/DiamondBounds.hpp b/Core/include/Acts/Surfaces/DiamondBounds.hpp
@@ -26,6 +26,7 @@ namespace Acts {
 
 /// @class DiamondBounds
 ///
+/// @image html DiamondBounds.svg
 /// Bounds for a double trapezoidal ("diamond"), planar Surface.
 class DiamondBounds : public PlanarBounds {
  public:

diff --git a/Core/include/Acts/Surfaces/DiscBounds.hpp b/Core/include/Acts/Surfaces/DiscBounds.hpp
@@ -14,6 +14,8 @@ namespace Acts {
 
 /// @class DiscBounds
 ///
+/// @image html DiscBounds.gif
+///
 /// common base class for all bounds that are in a r/phi frame
 ///  - simply introduced to avoid wrong bound assignments to surfaces
 

diff --git a/Core/include/Acts/Surfaces/DiscSurface.hpp b/Core/include/Acts/Surfaces/DiscSurface.hpp
@@ -48,7 +48,7 @@ class SurfaceBounds;
 /// to happen to transfer the local coordinates onto the
 /// cartesian reference frame coordinates.
 ///
-/// @image html figures/DiscSurface.png
+/// @image html DiscSurface.png
 ///
 class DiscSurface : public Surface {
 #ifndef DOXYGEN

diff --git a/Core/include/Acts/Surfaces/EllipseBounds.hpp b/Core/include/Acts/Surfaces/EllipseBounds.hpp
@@ -27,6 +27,8 @@ namespace Acts {
 
 /// @class EllipseBounds
 ///
+/// @image html EllipseBounds.png
+///
 /// Class to describe the bounds for a planar ellispoid
 /// surface.
 ///

diff --git a/Core/include/Acts/Surfaces/LineSurface.hpp b/Core/include/Acts/Surfaces/LineSurface.hpp
@@ -37,7 +37,7 @@ class SurfaceBounds;
 ///
 ///  @note It leaves the type() method virtual, so it can not be instantiated
 ///
-/// @image html figures/LineSurface.png
+/// @image html LineSurface.png
 class LineSurface : public Surface {
 #ifndef DOXYGEN
   friend Surface;
@@ -182,7 +182,7 @@ class LineSurface : public Surface {
   /// of @f$ \vec{d} @f$ on @f$ \vec{measX} @f$:<br> @f$ sign = -sign(\vec{d}
   /// \cdot \vec{measX}) @f$
   ///
-  /// @image html figures/SignOfDriftCircleD0.gif
+  /// @image html SignOfDriftCircleD0.gif
   ///
   /// @param gctx The current geometry context object, e.g. alignment
   /// @param position global 3D position - considered to be on surface but not

diff --git a/Core/include/Acts/Surfaces/PerigeeSurface.hpp b/Core/include/Acts/Surfaces/PerigeeSurface.hpp
@@ -26,7 +26,7 @@ namespace Acts {
 /// The Surface axis is fixed to be the z-axis of the Tracking frame.
 /// It inherits from StraingLineSurface.
 ///
-/// @image html figures/LineSurface.png
+/// @image html LineSurface.png
 class PerigeeSurface : public LineSurface {
 #ifndef DOXYGEN
   friend Surface;

diff --git a/Core/include/Acts/Surfaces/PlaneSurface.hpp b/Core/include/Acts/Surfaces/PlaneSurface.hpp
@@ -37,12 +37,10 @@ class SurfaceBounds;
 /// The PlaneSurface extends the Surface class with the possibility to
 /// convert local to global positions (vice versa).
 ///
-/// @image html figures/PlaneSurface.png
+/// @image html PlaneSurface.png
 ///
 class PlaneSurface : public Surface {
-#ifndef DOXYGEN
-  friend Surface;
-#endif
+  friend class Surface;
 
  protected:
   /// Copy Constructor

diff --git a/Core/include/Acts/Surfaces/RectangleBounds.hpp b/Core/include/Acts/Surfaces/RectangleBounds.hpp
@@ -24,6 +24,8 @@ namespace Acts {
 
 /// @class RectangleBounds
 ///
+/// @image html RectangleBounds.gif
+///
 /// Bounds for a rectangular, planar surface - it can be used to for
 /// rectangles that are symmetrically centered around (0./0.) and for
 /// generic shifted rectangles

diff --git a/Core/include/Acts/Surfaces/StrawSurface.hpp b/Core/include/Acts/Surfaces/StrawSurface.hpp
@@ -29,12 +29,10 @@ class LineBounds;
 ///  Class for a StrawSurface in the TrackingGeometry
 ///  to describe dirft tube and straw like detectors.
 ///
-/// @image html figures/LineSurface.png
+/// @image html LineSurface.png
 ///
 class StrawSurface : public LineSurface {
-#ifndef DOXYGEN
-  friend Surface;
-#endif
+  friend class Surface;
 
  protected:
   /// Constructor from Transform3 and bounds

diff --git a/Core/include/Acts/Surfaces/TrapezoidBounds.hpp b/Core/include/Acts/Surfaces/TrapezoidBounds.hpp
@@ -27,7 +27,7 @@ namespace Acts {
 ///
 /// Bounds for a trapezoidal, planar Surface.
 ///
-/// @image html figures/TrapezoidBounds.gif
+/// @image html TrapezoidBounds.gif
 ///
 /// @todo can be speed optimized by calculating kappa/delta and caching it
 

diff --git a/Core/include/Acts/Vertexing/AdaptiveMultiVertexFinder.hpp b/Core/include/Acts/Vertexing/AdaptiveMultiVertexFinder.hpp
@@ -169,7 +169,7 @@ class AdaptiveMultiVertexFinder {
   template <
       typename T = InputTrack_t,
       std::enable_if_t<std::is_same<T, BoundTrackParameters>::value, int> = 0>
-  AdaptiveMultiVertexFinder(Config& cfg,
+  AdaptiveMultiVertexFinder(Config cfg,
                             std::unique_ptr<const Logger> logger =
                                 getDefaultLogger("AdaptiveMultiVertexFinder",
                                                  Logging::INFO))
@@ -185,7 +185,7 @@ class AdaptiveMultiVertexFinder {
   /// object
   /// @param logger The logging instance
   AdaptiveMultiVertexFinder(
-      Config& cfg, std::function<BoundTrackParameters(InputTrack_t)> func,
+      Config cfg, std::function<BoundTrackParameters(InputTrack_t)> func,
       std::unique_ptr<const Logger> logger =
           getDefaultLogger("AdaptiveMultiVertexFinder", Logging::INFO))
       : m_cfg(std::move(cfg)),