refactor!: Put GSF in namespace Acts::Experimental (#1609)

Since the GSF is not yet fully functional, it is put in the namespace
`Acts::Experimental`.

Also adds some hints in the documentation, that components in this
namespace are not yet production read, and also not part of the public
API (I think that is reasonable, since clients should not rely on
experimental code).

However, since this would be a new rule, this change is breaking.

Co-authored-by: Benjamin Huth <[email protected]>
Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>

Core/include/Acts/TrackFitting/GaussianSumFitter.hpp

@@ -42,6 +42,8 @@ struct IsMultiComponentBoundParameters<MultiComponentBoundTrackParameters<T>>
 
 }  // namespace detail
 
+namespace Experimental {
+
 /// Gaussian Sum Fitter implementation.
 /// @tparam propagator_t The propagator type on which the algorithm is built on
 /// @tparam bethe_heitler_approx_t The type of the Bethe-Heitler-Approximation
@@ -534,4 +536,5 @@ struct GaussianSumFitter {
   }
 };
 
+}  // namespace Experimental
 }  // namespace Acts

Core/include/Acts/TrackFitting/GsfError.hpp

@@ -11,6 +11,7 @@
 #include <system_error>
 
 namespace Acts {
+namespace Experimental {
 
 enum class GsfError {
   // ensure all values are non-zero
@@ -25,12 +26,13 @@ enum class GsfError {
   SmoothingFailed
 };
 
-std::error_code make_error_code(Acts::GsfError e);
+std::error_code make_error_code(GsfError e);
 
+}  // namespace Experimental
 }  // namespace Acts
 
 // register with STL
 namespace std {
 template <>
-struct is_error_code_enum<Acts::GsfError> : std::true_type {};
+struct is_error_code_enum<Acts::Experimental::GsfError> : std::true_type {};
 }  // namespace std

Core/include/Acts/TrackFitting/GsfOptions.hpp

@@ -18,6 +18,7 @@
 #include "Acts/Utilities/Logger.hpp"
 
 namespace Acts {
+namespace Experimental {
 
 /// The extensions needed for the GSF
 template <typename traj_t>
@@ -74,4 +75,5 @@ struct GsfOptions {
   bool disableAllMaterialHandling = false;
 };
 
+}  // namespace Experimental
 }  // namespace Acts

Core/include/Acts/TrackFitting/detail/GsfActor.hpp

@@ -107,7 +107,7 @@ struct GsfActor {
     std::optional<std::size_t> numberMeasurements;
 
     /// The extensions
-    GsfExtensions<traj_t> extensions;
+    Experimental::GsfExtensions<traj_t> extensions;
   } m_cfg;
 
   /// Stores meta information about the components
@@ -189,7 +189,8 @@ struct GsfActor {
                  << result.parentTips.size() << " vs "
                  << stepper.numberComponents(state.stepping));
 
-      return set_error_or_abort(GsfError::ComponentNumberMismatch);
+      return set_error_or_abort(
+          Experimental::GsfError::ComponentNumberMismatch);
     }
 
     // There seem to be cases where this is not always after initializing the

Core/include/Acts/TrackFitting/detail/GsfSmoothing.hpp

@@ -68,7 +68,7 @@ auto bayesianSmoothing(component_iterator_t fwdBegin,
   }
 
   if (smoothedState.empty()) {
-    return ResType(GsfError::SmoothingFailed);
+    return ResType(Experimental::GsfError::SmoothingFailed);
   }
 
   normalizeWeights(smoothedState, [](auto &tuple) -> decltype(auto) {

Core/src/TrackFitting/GsfError.cpp

@@ -17,7 +17,7 @@ class GsfErrorCategory : public std::error_category {
 
   // Return what each enum means in text.
   std::string message(int c) const final {
-    using Acts::GsfError;
+    using Acts::Experimental::GsfError;
 
     switch (static_cast<GsfError>(c)) {
       case GsfError::NavigationFailed:
@@ -47,7 +47,8 @@ class GsfErrorCategory : public std::error_category {
 
 }  // namespace
 
-std::error_code Acts::make_error_code(Acts::GsfError e) {
+std::error_code Acts::Experimental::make_error_code(
+    Acts::Experimental::GsfError e) {
   static GsfErrorCategory c;
   return {static_cast<int>(e), c};
 }

Examples/Algorithms/TrackFitting/src/GsfFitterFunction.cpp

@@ -27,10 +27,13 @@ namespace {
 
 using MultiStepper = Acts::MultiEigenStepperLoop<>;
 using Propagator = Acts::Propagator<MultiStepper, Acts::Navigator>;
-using Fitter = Acts::GaussianSumFitter<Propagator, Acts::VectorMultiTrajectory>;
+using Fitter =
+    Acts::Experimental::GaussianSumFitter<Propagator,
+                                          Acts::VectorMultiTrajectory>;
 using DirectPropagator = Acts::Propagator<MultiStepper, Acts::DirectNavigator>;
 using DirectFitter =
-    Acts::GaussianSumFitter<DirectPropagator, Acts::VectorMultiTrajectory>;
+    Acts::Experimental::GaussianSumFitter<DirectPropagator,
+                                          Acts::VectorMultiTrajectory>;
 
 struct GsfFitterFunctionImpl
     : public ActsExamples::TrackFittingAlgorithm::TrackFitterFunction {
@@ -49,12 +52,12 @@ struct GsfFitterFunctionImpl
   auto makeGsfOptions(
       const ActsExamples::TrackFittingAlgorithm::GeneralFitterOptions& options)
       const {
-    Acts::GsfExtensions<Acts::VectorMultiTrajectory> extensions;
+    Acts::Experimental::GsfExtensions<Acts::VectorMultiTrajectory> extensions;
     extensions.updater.connect<
         &Acts::GainMatrixUpdater::operator()<Acts::VectorMultiTrajectory>>(
         &updater);
 
-    Acts::GsfOptions<Acts::VectorMultiTrajectory> gsfOptions{
+    Acts::Experimental::GsfOptions<Acts::VectorMultiTrajectory> gsfOptions{
         options.geoContext,
         options.magFieldContext,
         options.calibrationContext,

Tests/UnitTests/Core/TrackFitting/GsfTests.cpp

@@ -27,6 +27,7 @@ namespace {
 using namespace Acts;
 using namespace Acts::Test;
 using namespace Acts::UnitLiterals;
+using namespace Acts::Experimental;
 
 Acts::GainMatrixUpdater kfUpdater;
 

docs/acts_project.md

@@ -9,7 +9,7 @@ Acts is designed as a library that *contains components* for assembling a track
 ```
 
 The library is structured as follows:
- * The `Core` library contains considered production ready components that can be interfaced to experiment code
+ * The `Core` library contains considered production ready components (except for components located in the `Acts::Experimental` namespace) that can be interfaced to experiment code
  * The `Plugin` folder contains additional extensions that can be optionally switched on to use increase the functionality of the software suite, but also in general increase dependencies to other/thirdparty libraries
  * The `Fatras` library contains a fast track simulation module, that is based on the same concepts that are used for the [ATLAS Fatras](https://cds.cern.ch/record/1091969) fast track simulation  
  * An `Examples` folder that contains a minimal test framework used for showcasing and integration testing, 

docs/core/track_fitting.md

@@ -34,6 +34,10 @@ This chapter will be extended in the future.
 (gsf_core)=
 ## Gaussian Sum Filter
 
+:::{note}
+The GSF is not considered as production ready yet, therefore it is located in the namespace `Acts::Experimental`.
+:::
+
 The GSF is an extension of the Kalman-Filter that allows to handle non-gaussian errors by modelling the track state as a gaussian mixture:
 
 $$
@@ -48,9 +52,9 @@ To implement the GSF, a special stepper is needed, that can handle a multi-compo
 
 ### Using the GSF
 
-The GSF is implemented in the class {class}`Acts::GaussianSumFitter`. The interface of its `fit(...)`-functions is very similar to the one of the {class}`Acts::KalmanFitter` (one for the standard {class}`Acts::Navigator` and one for the {class}`Acts::DirectNavigator` that takes an additional `std::vector<const Acts::Surface *>` as an argument):
+The GSF is implemented in the class {class}`Acts::Experimental::GaussianSumFitter`. The interface of its `fit(...)`-functions is very similar to the one of the {class}`Acts::KalmanFitter` (one for the standard {class}`Acts::Navigator` and one for the {class}`Acts::DirectNavigator` that takes an additional `std::vector<const Acts::Surface *>` as an argument):
 
-```{doxygenstruct} Acts::GaussianSumFitter
+```{doxygenstruct} Acts::Experimental::GaussianSumFitter
 ---
 members: fit
 outline:
@@ -67,9 +71,9 @@ A GSF example can be found in the Acts Examples Framework [here](https://github.
 
 To be able to evaluate the approximation of the Bethe-Heitler distribution for different materials and thicknesses, the individual gaussian components (weight, mean, variance of the ratio $E_f/E_i$) are parameterized as polynomials in $x/x_0$. The default parametrization uses 6 components and 5th order polynomials.
 
-This approximation of the Bethe-Heitler distribution is described in {class}`Acts::BetheHeitlerApprox`. The class is templated on the number of components and the degree of the polynomial, and is designed to be used with the [parameterization files from ATLAS](https://gitlab.cern.ch/atlas/athena/-/tree/master/Tracking/TrkFitter/TrkGaussianSumFilter/Data). However, in principle the GSF could be constructed with custom classes with the same interface as {class}`Acts::BetheHeitlerApprox`.
+This approximation of the Bethe-Heitler distribution is described in {class}`Acts::detail::BetheHeitlerApprox`. The class is templated on the number of components and the degree of the polynomial, and is designed to be used with the [parameterization files from ATLAS](https://gitlab.cern.ch/atlas/athena/-/tree/master/Tracking/TrkFitter/TrkGaussianSumFilter/Data). However, in principle the GSF could be constructed with custom classes with the same interface as {class}`Acts::detail::BetheHeitlerApprox`.
 
-For small $x/x_0$ the {class}`Acts::BetheHeitlerApprox` only returns a one-component mixture or no change at all. When loading a custom parametrization, it is possible to specify different parameterizations for high and for low $x/x_0$. The thresholds are currently not configurable.
+For small $x/x_0$ the {class}`Acts::detail::BetheHeitlerApprox` only returns a one-component mixture or no change at all. When loading a custom parametrization, it is possible to specify different parameterizations for high and for low $x/x_0$. The thresholds are currently not configurable.
 
 ### Further reading
 * *Thomas Atkinson*, Electron reconstruction with the ATLAS inner detector, 2006, see [here](https://cds.cern.ch/record/1448253)

docs/versioning.rst

@@ -43,6 +43,7 @@ The following components will never become part of the public API:
 
 - Symbols in helper namespaces e.g. in ``Acts::detail`` must be considered
   implementation details and are not part of the public API.
+- Symbols in the namespace ``Acts::Experimental`` are not part of the public API.
 - The examples framework and executables in the ``Examples`` directory.
 - All units tests, integration tests, (micro)-benchmarks, and related code in
   the ``Tests`` directory.