feat: Propagator accepts prepared result instance (#1317)

This PR adds overloads to the `Propagator::propagate` method which allow passing in a prepared result object. I want to use this to have the CKF reuse a single `MultiTrajectory` object for all input seeds, and @benjaminhuth might be able to use this to simplify the GSF internals.

Core/include/Acts/Propagator/Propagator.hpp

@@ -311,6 +311,7 @@ class Propagator final {
     using type = typename action_list_t::template result_type<this_result_type>;
   };
 
+ public:
   /// @brief Short-hand type definition for propagation result derived from
   ///        an action list
   ///
@@ -321,6 +322,7 @@ class Propagator final {
   using action_list_t_result_t =
       typename result_type_helper<parameters_t, action_list_t>::type;
 
+ private:
   /// @brief Propagate track parameters
   /// Private method with propagator and stepper state
   ///
@@ -335,10 +337,12 @@ class Propagator final {
   /// @tparam propagator_state_t Type of of propagator state with options
   ///
   /// @param [in,out] state the propagator state object
+  /// @param [in,out] result an existing result object to start from
   ///
   /// @return Propagation result
   template <typename result_t, typename propagator_state_t>
-  Result<result_t> propagate_impl(propagator_state_t& state) const;
+  Result<void> propagate_impl(propagator_state_t& state,
+                              result_t& result) const;
 
  public:
   /// @brief Propagate track parameters
@@ -349,9 +353,8 @@ class Propagator final {
   /// propagation options is reached.
   ///
   /// @tparam parameters_t Type of initial track parameters to propagate
-  /// @tparam action_list_t Type list of actions, type ActionList<>
-  /// @tparam aborter_list_t Type list of abort conditions, type AbortList<>
   /// @tparam propagator_options_t Type of the propagator options
+  /// @tparam path_aborter_t The path aborter type to be added
   ///
   /// @param [in] start initial track parameters to propagate
   /// @param [in] options Propagation options, type Options<,>
@@ -367,6 +370,35 @@ class Propagator final {
   propagate(const parameters_t& start,
             const propagator_options_t& options) const;
 
+  /// @brief Propagate track parameters
+  ///
+  /// This function performs the propagation of the track parameters using the
+  /// internal stepper implementation, until at least one abort condition is
+  /// fulfilled or the maximum number of steps/path length provided in the
+  /// propagation options is reached.
+  ///
+  /// @tparam parameters_t Type of initial track parameters to propagate
+  /// @tparam propagator_options_t Type of the propagator options
+  /// @tparam path_aborter_t The path aborter type to be added
+  ///
+  /// @param [in] start initial track parameters to propagate
+  /// @param [in] options Propagation options, type Options<,>
+  /// @param [in] inputResult an existing result object to start from
+  ///
+  /// @return Propagation result containing the propagation status, final
+  ///         track parameters, and output of actions (if they produce any)
+  ///
+  template <typename parameters_t, typename propagator_options_t,
+            typename path_aborter_t = PathLimitReached>
+  Result<
+      action_list_t_result_t<CurvilinearTrackParameters,
+                             typename propagator_options_t::action_list_type>>
+  propagate(
+      const parameters_t& start, const propagator_options_t& options,
+      action_list_t_result_t<CurvilinearTrackParameters,
+                             typename propagator_options_t::action_list_type>&&
+          inputResult) const;
+
   /// @brief Propagate track parameters - User method
   ///
   /// This function performs the propagation of the track parameters according
@@ -375,10 +407,9 @@ class Propagator final {
   /// steps/path length as given in the propagation options is reached.
   ///
   /// @tparam parameters_t Type of initial track parameters to propagate
-  /// @tparam surface_t Type of target surface
-  /// @tparam action_list_t Type list of actions
-  /// @tparam aborter_list_t Type list of abort conditions
   /// @tparam propagator_options_t Type of the propagator options
+  /// @tparam target_aborter_t The target aborter type to be added
+  /// @tparam path_aborter_t The path aborter type to be added
   ///
   /// @param [in] start Initial track parameters to propagate
   /// @param [in] target Target surface of to propagate to
@@ -394,6 +425,37 @@ class Propagator final {
   propagate(const parameters_t& start, const Surface& target,
             const propagator_options_t& options) const;
 
+  /// @brief Propagate track parameters - User method
+  ///
+  /// This function performs the propagation of the track parameters according
+  /// to the internal implementation object until at least one abort condition
+  /// is fulfilled, the destination surface is hit or the maximum number of
+  /// steps/path length as given in the propagation options is reached.
+  ///
+  /// @tparam parameters_t Type of initial track parameters to propagate
+  /// @tparam propagator_options_t Type of the propagator options
+  /// @tparam target_aborter_t The target aborter type to be added
+  /// @tparam path_aborter_t The path aborter type to be added
+  ///
+  /// @param [in] start Initial track parameters to propagate
+  /// @param [in] target Target surface of to propagate to
+  /// @param [in] options Propagation options
+  /// @param [in] inputResult an existing result object to start from
+  ///
+  /// @return Propagation result containing the propagation status, final
+  ///         track parameters, and output of actions (if they produce any)
+  template <typename parameters_t, typename propagator_options_t,
+            typename target_aborter_t = SurfaceReached,
+            typename path_aborter_t = PathLimitReached>
+  Result<action_list_t_result_t<
+      BoundTrackParameters, typename propagator_options_t::action_list_type>>
+  propagate(
+      const parameters_t& start, const Surface& target,
+      const propagator_options_t& options,
+      action_list_t_result_t<BoundTrackParameters,
+                             typename propagator_options_t::action_list_type>
+          inputResult) const;
+
  private:
   /// Implementation of propagation algorithm
   stepper_t m_stepper;

Core/include/Acts/Propagator/Propagator.ipp

@@ -10,10 +10,9 @@
 
 template <typename S, typename N>
 template <typename result_t, typename propagator_state_t>
-auto Acts::Propagator<S, N>::propagate_impl(propagator_state_t& state) const
-    -> Result<result_t> {
-  result_t result;
-
+auto Acts::Propagator<S, N>::propagate_impl(propagator_state_t& state,
+                                            result_t& result) const
+    -> Result<void> {
   const auto& logger = state.options.logger;
 
   // Pre-stepping call to the navigator and action list
@@ -82,7 +81,7 @@ auto Acts::Propagator<S, N>::propagate_impl(propagator_state_t& state) const
   state.options.actionList(state, m_stepper, result);
 
   // return progress flag here, decide on SUCCESS later
-  return Result<result_t>(std::move(result));
+  return Result<void>::success();
 }
 
 template <typename S, typename N>
@@ -93,17 +92,40 @@ auto Acts::Propagator<S, N>::propagate(
     -> Result<action_list_t_result_t<
         CurvilinearTrackParameters,
         typename propagator_options_t::action_list_type>> {
-  static_assert(Concepts::BoundTrackParametersConcept<parameters_t>,
-                "Parameters do not fulfill bound parameters concept.");
-
   // Type of track parameters produced by the propagation
   using ReturnParameterType = CurvilinearTrackParameters;
 
+  static_assert(std::is_copy_constructible<ReturnParameterType>::value,
+                "return track parameter type must be copy-constructible");
+
   // Type of the full propagation result, including output from actions
   using ResultType =
       action_list_t_result_t<ReturnParameterType,
                              typename propagator_options_t::action_list_type>;
 
+  return propagate<parameters_t, propagator_options_t, path_aborter_t>(
+      start, options, ResultType{});
+}
+
+template <typename S, typename N>
+template <typename parameters_t, typename propagator_options_t,
+          typename path_aborter_t>
+auto Acts::Propagator<S, N>::propagate(
+    const parameters_t& start, const propagator_options_t& options,
+    action_list_t_result_t<CurvilinearTrackParameters,
+                           typename propagator_options_t::action_list_type>&&
+        inputResult) const
+    -> Result<action_list_t_result_t<
+        CurvilinearTrackParameters,
+        typename propagator_options_t::action_list_type>> {
+  static_assert(Concepts::BoundTrackParametersConcept<parameters_t>,
+                "Parameters do not fulfill bound parameters concept.");
+
+  using ResultType = std::decay_t<decltype(inputResult)>;
+
+  // Type of track parameters produced by the propagation
+  using ReturnParameterType = CurvilinearTrackParameters;
+
   static_assert(std::is_copy_constructible<ReturnParameterType>::value,
                 "return track parameter type must be copy-constructible");
 
@@ -136,22 +158,21 @@ auto Acts::Propagator<S, N>::propagate(
     lProtection(state, m_stepper);
   }
   // Perform the actual propagation & check its outcome
-  auto result = propagate_impl<ResultType>(state);
+  auto result = propagate_impl<ResultType>(state, inputResult);
   if (result.ok()) {
-    auto& propRes = *result;
     /// Convert into return type and fill the result object
     auto curvState = m_stepper.curvilinearState(state.stepping);
     auto& curvParameters = std::get<CurvilinearTrackParameters>(curvState);
     // Fill the end parameters
-    propRes.endParameters =
+    inputResult.endParameters =
         std::make_unique<CurvilinearTrackParameters>(std::move(curvParameters));
     // Only fill the transport jacobian when covariance transport was done
     if (state.stepping.covTransport) {
       auto& tJacobian = std::get<Jacobian>(curvState);
-      propRes.transportJacobian =
+      inputResult.transportJacobian =
           std::make_unique<Jacobian>(std::move(tJacobian));
     }
-    return result;
+    return Result<ResultType>::success(std::forward<ResultType>(inputResult));
   } else {
     return result.error();
   }
@@ -172,6 +193,32 @@ auto Acts::Propagator<S, N>::propagate(
   // Type of track parameters produced at the end of the propagation
   using return_parameter_type = BoundTrackParameters;
 
+  // Type of the full propagation result, including output from actions
+  using ResultType =
+      action_list_t_result_t<return_parameter_type,
+                             typename propagator_options_t::action_list_type>;
+
+  return propagate<parameters_t, propagator_options_t, target_aborter_t,
+                   path_aborter_t>(start, target, options, ResultType{});
+}
+
+template <typename S, typename N>
+template <typename parameters_t, typename propagator_options_t,
+          typename target_aborter_t, typename path_aborter_t>
+auto Acts::Propagator<S, N>::propagate(
+    const parameters_t& start, const Surface& target,
+    const propagator_options_t& options,
+    action_list_t_result_t<BoundTrackParameters,
+                           typename propagator_options_t::action_list_type>
+        inputResult) const
+    -> Result<action_list_t_result_t<
+        BoundTrackParameters,
+        typename propagator_options_t::action_list_type>> {
+  static_assert(Concepts::BoundTrackParametersConcept<parameters_t>,
+                "Parameters do not fulfill bound parameters concept.");
+
+  using ResultType = std::decay_t<decltype(inputResult)>;
+
   // Type of provided options
   target_aborter_t targetAborter;
   path_aborter_t pathAborter;
@@ -182,11 +229,6 @@ auto Acts::Propagator<S, N>::propagate(
   auto eOptions = options.extend(abortList);
   using OptionsType = decltype(eOptions);
 
-  // Type of the full propagation result, including output from actions
-  using ResultType =
-      action_list_t_result_t<return_parameter_type,
-                             typename propagator_options_t::action_list_type>;
-
   // Initialize the internal propagator state
   using StateType = State<OptionsType>;
   StateType state{
@@ -207,10 +249,9 @@ auto Acts::Propagator<S, N>::propagate(
   lProtection(state, m_stepper);
 
   // Perform the actual propagation
-  auto result = propagate_impl<ResultType>(state);
+  auto result = propagate_impl<ResultType>(state, inputResult);
 
   if (result.ok()) {
-    auto& propRes = *result;
     // Compute the final results and mark the propagation as successful
     auto bsRes = m_stepper.boundState(state.stepping, target);
     if (!bsRes.ok()) {
@@ -221,15 +262,15 @@ auto Acts::Propagator<S, N>::propagate(
 
     auto& boundParams = std::get<BoundTrackParameters>(bs);
     // Fill the end parameters
-    propRes.endParameters =
+    inputResult.endParameters =
         std::make_unique<BoundTrackParameters>(std::move(boundParams));
     // Only fill the transport jacobian when covariance transport was done
     if (state.stepping.covTransport) {
       auto& tJacobian = std::get<Jacobian>(bs);
-      propRes.transportJacobian =
+      inputResult.transportJacobian =
           std::make_unique<Jacobian>(std::move(tJacobian));
     }
-    return result;
+    return Result<ResultType>::success(std::forward<ResultType>(inputResult));
   } else {
     return result.error();
   }