Acts/EventData/TrackStateProxyCommon.hpp

0001 // This file is part of the ACTS project.
0002 //
0003 // Copyright (C) 2016 CERN for the benefit of the ACTS project
0004 //
0005 // This Source Code Form is subject to the terms of the Mozilla Public
0006 // License, v. 2.0. If a copy of the MPL was not distributed with this
0007 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
0008
0009 #pragma once
0010
0011 #include "Acts/EventData/SubspaceHelpers.hpp"
0012 #include "Acts/EventData/TrackStatePropMask.hpp"
0013 #include "Acts/EventData/TrackStateType.hpp"
0014 #include "Acts/EventData/Types.hpp"
0015 #include "Acts/Utilities/EigenConcepts.hpp"
0016 #include "Acts/Utilities/HashedString.hpp"
0017
0018 #include <algorithm>
0019 #include <ranges>
0020 #include <string_view>
0021
0022 namespace Acts {
0023
0024 namespace detail_tsp {
0025 inline constexpr HashedString kPreviousKey = hashString("previous");
0026 inline constexpr HashedString kChi2Key = hashString("chi2");
0027 inline constexpr HashedString kPathLengthKey = hashString("pathLength");
0028 inline constexpr HashedString kTypeFlagsKey = hashString("typeFlags");
0029 inline constexpr HashedString kPredictedKey = hashString("predicted");
0030 inline constexpr HashedString kFilteredKey = hashString("filtered");
0031 inline constexpr HashedString kSmoothedKey = hashString("smoothed");
0032 inline constexpr HashedString kJacobianKey = hashString("jacobian");
0033 inline constexpr HashedString kProjectorKey = hashString("projector");
0034 inline constexpr HashedString kUncalibratedKey =
0035     hashString("uncalibratedSourceLink");
0036 inline constexpr HashedString kCalibratedKey = hashString("calibrated");
0037 inline constexpr HashedString kCalibratedCovKey = hashString("calibratedCov");
0038 inline constexpr HashedString kMeasDimKey = hashString("measdim");
0039 inline constexpr HashedString kNextKey = hashString("next");
0040
0041 }  // namespace detail_tsp
0042
0043 /// Common CRTP implementation shared by track state proxy front-ends.
0044 /// This base class provides access to track state components including
0045 /// predicted, filtered, and smoothed parameters and covariances, as well as
0046 /// calibrated measurement data and various metadata. The derived proxy must
0047 /// expose the underlying storage access methods.
0048 ///
0049 /// @tparam Derived The proxy implementation inheriting from this base
0050 /// @tparam read_only Whether the proxy provides mutable access
0051 template <typename Derived, bool read_only>
0052 class TrackStateProxyCommon {
0053  protected:
0054   using IndexType = Acts::TrackIndexType;
0055
0056   constexpr Derived& derived() { return static_cast<Derived&>(*this); }
0057   constexpr const Derived& derived() const {
0058     return static_cast<const Derived&>(*this);
0059   }
0060
0061  public:
0062   /// Retrieve the previous track state index in the linked trajectory.
0063   /// @return Index of the previous state or `kTrackIndexInvalid`.
0064   TrackIndexType previous() const {
0065     return derived()
0066         .template component<TrackIndexType, detail_tsp::kPreviousKey>();
0067   }
0068
0069   /// Retrieve a mutable reference to the previous track state index.
0070   /// @return Mutable index of the previous state.
0071   TrackIndexType& previous()
0072     requires(!read_only)
0073   {
0074     return derived()
0075         .template component<TrackIndexType, detail_tsp::kPreviousKey>();
0076   }
0077
0078   /// Check whether this state links to a previous state.
0079   /// @return True if the previous index is valid.
0080   bool hasPrevious() const { return previous() != kTrackIndexInvalid; }
0081
0082   /// Check for presence of predicted track parameters.
0083   /// @return True if the predicted component exists.
0084   bool hasPredicted() const { return derived().has(detail_tsp::kPredictedKey); }
0085
0086   /// Check for presence of filtered track parameters.
0087   /// @return True if the filtered component exists.
0088   bool hasFiltered() const { return derived().has(detail_tsp::kFilteredKey); }
0089
0090   /// Check for presence of smoothed track parameters.
0091   /// @return True if the smoothed component exists.
0092   bool hasSmoothed() const { return derived().has(detail_tsp::kSmoothedKey); }
0093
0094   /// Check for presence of a transport Jacobian.
0095   /// @return True if a Jacobian is stored.
0096   bool hasJacobian() const { return derived().has(detail_tsp::kJacobianKey); }
0097
0098   /// Check for presence of a measurement projector.
0099   /// @return True if projector indices are stored.
0100   bool hasProjector() const { return derived().has(detail_tsp::kProjectorKey); }
0101
0102   /// Check for presence of calibrated measurement data.
0103   /// @return True if calibrated measurements exist.
0104   bool hasCalibrated() const {
0105     return derived().has(detail_tsp::kCalibratedKey);
0106   }
0107
0108   /// @name Type aliases for parameter and covariance access
0109   /// @{
0110
0111   /// Mutable Eigen map type for bound track parameters.
0112   using ParametersMap =
0113       typename detail_tsp::FixedSizeTypes<eBoundSize, false>::CoefficientsMap;
0114   /// Const Eigen map type for bound track parameters.
0115   using ConstParametersMap =
0116       typename detail_tsp::FixedSizeTypes<eBoundSize, true>::CoefficientsMap;
0117   /// Mutable Eigen map type for bound track parameter covariance.
0118   using CovarianceMap =
0119       typename detail_tsp::FixedSizeTypes<eBoundSize, false>::CovarianceMap;
0120   /// Const Eigen map type for bound track parameter covariance.
0121   using ConstCovarianceMap =
0122       typename detail_tsp::FixedSizeTypes<eBoundSize, true>::CovarianceMap;
0123
0124   /// Mutable Eigen map type for calibrated measurements (dynamic size).
0125   using EffectiveCalibratedMap =
0126       typename detail_tsp::DynamicSizeTypes<false>::CoefficientsMap;
0127   /// Const Eigen map type for calibrated measurements (dynamic size).
0128   using ConstEffectiveCalibratedMap =
0129       typename detail_tsp::DynamicSizeTypes<true>::CoefficientsMap;
0130   /// Mutable Eigen map type for calibrated measurement covariance (dynamic
0131   /// size).
0132   using EffectiveCalibratedCovarianceMap =
0133       typename detail_tsp::DynamicSizeTypes<false>::CovarianceMap;
0134   /// Const Eigen map type for calibrated measurement covariance (dynamic size).
0135   using ConstEffectiveCalibratedCovarianceMap =
0136       typename detail_tsp::DynamicSizeTypes<true>::CovarianceMap;
0137
0138   /// @}
0139
0140   /// Access the predicted parameter vector.
0141   /// @return Bound parameter map for the predicted state.
0142   ConstParametersMap predicted() const {
0143     assert(hasPredicted());
0144     const auto parIndex =
0145         derived().template component<IndexType>(detail_tsp::kPredictedKey);
0146     return derived().parametersAtIndex(parIndex);
0147   }
0148
0149   /// Access the predicted parameter vector.
0150   /// @return Mutable bound parameter map for the predicted state.
0151   ParametersMap predicted()
0152     requires(!read_only)
0153   {
0154     assert(hasPredicted());
0155     const auto parIndex =
0156         derived().template component<IndexType>(detail_tsp::kPredictedKey);
0157     return derived().parametersAtIndexMutable(parIndex);
0158   }
0159
0160   /// Access the predicted covariance matrix.
0161   /// @return Bound covariance map for the predicted state.
0162   ConstCovarianceMap predictedCovariance() const {
0163     assert(hasPredicted());
0164     const auto covIndex =
0165         derived().template component<IndexType>(detail_tsp::kPredictedKey);
0166     return derived().covarianceAtIndex(covIndex);
0167   }
0168
0169   /// Access the predicted covariance matrix.
0170   /// @return Mutable bound covariance map for the predicted state.
0171   CovarianceMap predictedCovariance()
0172     requires(!read_only)
0173   {
0174     assert(hasPredicted());
0175     const auto covIndex =
0176         derived().template component<IndexType>(detail_tsp::kPredictedKey);
0177     return derived().covarianceAtIndexMutable(covIndex);
0178   }
0179
0180   /// Access the filtered parameter vector.
0181   /// @return Bound parameter map for the filtered state.
0182   ConstParametersMap filtered() const {
0183     assert(hasFiltered());
0184     const auto parIndex =
0185         derived().template component<IndexType>(detail_tsp::kFilteredKey);
0186     return derived().parametersAtIndex(parIndex);
0187   }
0188
0189   /// Access the filtered parameter vector.
0190   /// @return Mutable bound parameter map for the filtered state.
0191   ParametersMap filtered()
0192     requires(!read_only)
0193   {
0194     const auto parIndex =
0195         derived().template component<IndexType>(detail_tsp::kFilteredKey);
0196     return derived().parametersAtIndexMutable(parIndex);
0197   }
0198
0199   /// Access the filtered covariance matrix.
0200   /// @return Bound covariance map for the filtered state.
0201   ConstCovarianceMap filteredCovariance() const {
0202     assert(hasFiltered());
0203     const auto covIndex =
0204         derived().template component<IndexType>(detail_tsp::kFilteredKey);
0205     return derived().covarianceAtIndex(covIndex);
0206   }
0207
0208   /// Access the filtered covariance matrix.
0209   /// @return Mutable bound covariance map for the filtered state.
0210   CovarianceMap filteredCovariance()
0211     requires(!read_only)
0212   {
0213     const auto covIndex =
0214         derived().template component<IndexType>(detail_tsp::kFilteredKey);
0215     return derived().covarianceAtIndexMutable(covIndex);
0216   }
0217
0218   /// Access the smoothed parameter vector.
0219   /// @return Bound parameter map for the smoothed state.
0220   ConstParametersMap smoothed() const {
0221     assert(hasSmoothed());
0222     const auto parIndex =
0223         derived().template component<IndexType>(detail_tsp::kSmoothedKey);
0224     return derived().parametersAtIndex(parIndex);
0225   }
0226
0227   /// Access the smoothed parameter vector.
0228   /// @return Mutable bound parameter map for the smoothed state.
0229   ParametersMap smoothed()
0230     requires(!read_only)
0231   {
0232     assert(hasSmoothed());
0233     const auto parIndex =
0234         derived().template component<IndexType>(detail_tsp::kSmoothedKey);
0235     return derived().parametersAtIndexMutable(parIndex);
0236   }
0237
0238   /// Access the smoothed covariance matrix.
0239   /// @return Bound covariance map for the smoothed state.
0240   ConstCovarianceMap smoothedCovariance() const {
0241     assert(hasSmoothed());
0242     const auto covIndex =
0243         derived().template component<IndexType>(detail_tsp::kSmoothedKey);
0244     return derived().covarianceAtIndex(covIndex);
0245   }
0246
0247   /// Access the smoothed covariance matrix.
0248   /// @return Mutable bound covariance map for the smoothed state.
0249   CovarianceMap smoothedCovariance()
0250     requires(!read_only)
0251   {
0252     assert(hasSmoothed());
0253     const auto covIndex =
0254         derived().template component<IndexType>(detail_tsp::kSmoothedKey);
0255     return derived().covarianceAtIndexMutable(covIndex);
0256   }
0257
0258   /// Retrieve the accumulated path length.
0259   /// @return Path length stored on the state.
0260   double pathLength() const {
0261     return derived().template component<double, detail_tsp::kPathLengthKey>();
0262   }
0263
0264   /// Retrieve a mutable reference to the accumulated path length.
0265   /// @return Mutable path length.
0266   double& pathLength()
0267     requires(!read_only)
0268   {
0269     return derived().template component<double, detail_tsp::kPathLengthKey>();
0270   }
0271
0272   /// Retrieve the track-state type flags.
0273   /// @return Bit mask describing the state type.
0274   ConstTrackStateTypeMap typeFlags() const {
0275     const auto& raw = derived()
0276                           .template component<ConstTrackStateTypeMap::raw_type,
0277                                               detail_tsp::kTypeFlagsKey>();
0278     return ConstTrackStateTypeMap{raw};
0279   }
0280
0281   /// Retrieve mutable track-state type flags.
0282   /// @return Mutable bit mask describing the state type.
0283   MutableTrackStateTypeMap typeFlags()
0284     requires(!read_only)
0285   {
0286     auto& raw = derived()
0287                     .template component<MutableTrackStateTypeMap::raw_type,
0288                                         detail_tsp::kTypeFlagsKey>();
0289     return MutableTrackStateTypeMap{raw};
0290   }
0291
0292   /// Retrieve the local chi2 contribution.
0293   /// @return Chi2 value associated with this state.
0294   float chi2() const {
0295     return derived().template component<float, detail_tsp::kChi2Key>();
0296   }
0297
0298   /// Retrieve a mutable reference to the local chi2 contribution.
0299   /// @return Mutable chi2 value.
0300   float& chi2()
0301     requires(!read_only)
0302   {
0303     return derived().template component<float, detail_tsp::kChi2Key>();
0304   }
0305
0306   /// Decode the measurement projector indices.
0307   /// @return Bound parameter indices used for projection.
0308   BoundSubspaceIndices projectorSubspaceIndices() const {
0309     assert(hasProjector());
0310     const auto& serialized =
0311         derived()
0312             .template component<SerializedSubspaceIndices,
0313                                 detail_tsp::kProjectorKey>();
0314     return deserializeSubspaceIndices<eBoundSize>(serialized);
0315   }
0316
0317   /// Returns the projector subspace indices
0318   /// @return The projector subspace indices
0319   template <std::size_t measdim>
0320   SubspaceIndices<measdim> projectorSubspaceIndices() const {
0321     BoundSubspaceIndices boundSubspace = projectorSubspaceIndices();
0322     SubspaceIndices<measdim> subspace;
0323     std::copy(boundSubspace.begin(), boundSubspace.begin() + measdim,
0324               subspace.begin());
0325     return subspace;
0326   }
0327
0328   /// Creates a variable size subspace helper
0329   /// @return The subspace helper
0330   VariableBoundSubspaceHelper projectorSubspaceHelper() const {
0331     BoundSubspaceIndices boundSubspace = projectorSubspaceIndices();
0332     std::span<std::uint8_t> validSubspaceIndices(
0333         boundSubspace.begin(),
0334         boundSubspace.begin() + derived().calibratedSize());
0335     return VariableBoundSubspaceHelper(validSubspaceIndices);
0336   }
0337
0338   /// Creates a fixed size subspace helper
0339   /// @return The subspace helper
0340   template <std::size_t measdim>
0341   FixedBoundSubspaceHelper<measdim> projectorSubspaceHelper() const {
0342     SubspaceIndices<measdim> subspace = projectorSubspaceIndices<measdim>();
0343     return FixedBoundSubspaceHelper<measdim>(subspace);
0344   }
0345
0346   /// Store subspace indices describing the measurement projector.
0347   /// @tparam index_range_t Range of indices to encode.
0348   /// @param subspaceIndices Collection of bound indices forming the projector rows.
0349   template <std::ranges::sized_range index_range_t>
0350   void setProjectorSubspaceIndices(const index_range_t& subspaceIndices)
0351     requires(!read_only &&
0352              std::convertible_to<std::ranges::range_value_t<index_range_t>,
0353                                  std::uint8_t>)
0354   {
0355     assert(derived().template has<detail_tsp::kProjectorKey>());
0356     assert(subspaceIndices.size() <= eBoundSize);
0357     BoundSubspaceIndices boundSubspace{};
0358     std::transform(subspaceIndices.begin(), subspaceIndices.end(),
0359                    boundSubspace.begin(),
0360                    [](auto i) { return static_cast<std::uint8_t>(i); });
0361     derived()
0362         .template component<SerializedSubspaceIndices,
0363                             detail_tsp::kProjectorKey>() =
0364         serializeSubspaceIndices(boundSubspace);
0365   }
0366
0367   /// Compute the property mask describing which components are present.
0368   /// @return Bit mask of available properties.
0369   TrackStatePropMask getMask() const {
0370     using PM = TrackStatePropMask;
0371     PM mask = PM::None;
0372     if (hasPredicted()) {
0373       mask |= PM::Predicted;
0374     }
0375     if (hasFiltered()) {
0376       mask |= PM::Filtered;
0377     }
0378     if (hasSmoothed()) {
0379       mask |= PM::Smoothed;
0380     }
0381     if (hasJacobian()) {
0382       mask |= PM::Jacobian;
0383     }
0384     if (hasCalibrated()) {
0385       mask |= PM::Calibrated;
0386     }
0387     return mask;
0388   }
0389
0390   /// Access the best available parameters (smoothed, filtered, or predicted).
0391   /// @return Bound parameter map for the state.
0392   ConstParametersMap parameters() const {
0393     if (hasSmoothed()) {
0394       return smoothed();
0395     } else if (hasFiltered()) {
0396       return filtered();
0397     }
0398     return predicted();
0399   }
0400
0401   /// Access the best available covariance (smoothed, filtered, or predicted).
0402   /// @return Bound covariance map for the state.
0403   ConstCovarianceMap covariance() const {
0404     if (hasSmoothed()) {
0405       return smoothedCovariance();
0406     } else if (hasFiltered()) {
0407       return filteredCovariance();
0408     }
0409     return predictedCovariance();
0410   }
0411
0412   /// Access the calibrated measurement values with runtime dimension.
0413   /// @return Eigen map referencing the calibrated measurement vector.
0414   ConstEffectiveCalibratedMap effectiveCalibrated() const {
0415     const double* data = derived().calibratedData();
0416     const auto size = derived().calibratedSize();
0417     return ConstEffectiveCalibratedMap{data, size};
0418   }
0419
0420   /// Access mutable calibrated measurement values with runtime dimension.
0421   /// @return Eigen map referencing the calibrated measurement vector.
0422   EffectiveCalibratedMap effectiveCalibrated()
0423     requires(!read_only)
0424   {
0425     double* data = derived().calibratedDataMutable();
0426     const auto size = derived().calibratedSize();
0427     return EffectiveCalibratedMap{data, size};
0428   }
0429
0430   /// Access the calibrated covariance with runtime dimension.
0431   /// @return Eigen map referencing the measurement covariance matrix.
0432   ConstEffectiveCalibratedCovarianceMap effectiveCalibratedCovariance() const {
0433     const double* data = derived().calibratedCovarianceData();
0434     const auto size = derived().calibratedSize();
0435     return ConstEffectiveCalibratedCovarianceMap{data, size, size};
0436   }
0437
0438   /// Access mutable calibrated covariance with runtime dimension.
0439   /// @return Eigen map referencing the measurement covariance matrix.
0440   EffectiveCalibratedCovarianceMap effectiveCalibratedCovariance()
0441     requires(!read_only)
0442   {
0443     double* data = derived().calibratedCovarianceDataMutable();
0444     const auto size = derived().calibratedSize();
0445     return EffectiveCalibratedCovarianceMap{data, size, size};
0446   }
0447
0448   /// Access calibrated measurement data with compile-time dimension.
0449   /// @tparam measdim Measurement dimension.
0450   /// @return Eigen map referencing the calibrated measurement vector.
0451   template <std::size_t measdim>
0452   typename TrackStateTraits<measdim, true>::Calibrated calibrated() const {
0453     assert(derived().calibratedSize() == static_cast<TrackIndexType>(measdim));
0454     const double* data = derived().calibratedData();
0455     return typename TrackStateTraits<measdim, true>::Calibrated(data);
0456   }
0457
0458   /// Access calibrated measurement data with compile-time dimension.
0459   /// @tparam measdim Measurement dimension.
0460   /// @return Mutable Eigen map referencing the calibrated measurement vector.
0461   template <std::size_t measdim>
0462   typename TrackStateTraits<measdim, false>::Calibrated calibrated()
0463     requires(!read_only)
0464   {
0465     assert(derived().calibratedSize() == static_cast<TrackIndexType>(measdim));
0466     double* data = derived().calibratedDataMutable();
0467     return typename TrackStateTraits<measdim, false>::Calibrated(data);
0468   }
0469
0470   /// Access calibrated covariance data with compile-time dimension.
0471   /// @tparam measdim Measurement dimension.
0472   /// @return Eigen map referencing the covariance matrix.
0473   template <std::size_t measdim>
0474   typename TrackStateTraits<measdim, true>::CalibratedCovariance
0475   calibratedCovariance() const {
0476     assert(derived().calibratedSize() == static_cast<TrackIndexType>(measdim));
0477     const double* data = derived().calibratedCovarianceData();
0478     return typename TrackStateTraits<measdim, true>::CalibratedCovariance(data);
0479   }
0480
0481   /// Access calibrated covariance data with compile-time dimension.
0482   /// @tparam measdim Measurement dimension.
0483   /// @return Mutable Eigen map referencing the covariance matrix.
0484   template <std::size_t measdim>
0485   typename TrackStateTraits<measdim, false>::CalibratedCovariance
0486   calibratedCovariance()
0487     requires(!read_only)
0488   {
0489     assert(derived().calibratedSize() == static_cast<TrackIndexType>(measdim));
0490     double* data = derived().calibratedCovarianceDataMutable();
0491     return
0492         typename TrackStateTraits<measdim, false>::CalibratedCovariance(data);
0493   }
0494
0495   /// Allocate and initialize calibrated data from static-size Eigen objects.
0496   /// @tparam val_t Eigen vector type holding calibrated values.
0497   /// @tparam cov_t Eigen matrix type holding the covariance.
0498   /// @param val Vector to copy into the calibrated storage.
0499   /// @param cov Covariance matrix to copy into the calibrated storage.
0500   template <typename val_t, typename cov_t>
0501   void allocateCalibrated(const Eigen::DenseBase<val_t>& val,
0502                           const Eigen::DenseBase<cov_t>& cov)
0503     requires(!read_only && Concepts::eigen_base_is_fixed_size<val_t> &&
0504              Concepts::eigen_bases_have_same_num_rows<val_t, cov_t> &&
0505              Concepts::eigen_base_is_square<cov_t> &&
0506              Eigen::PlainObjectBase<val_t>::RowsAtCompileTime <=
0507                  static_cast<std::underlying_type_t<BoundIndices>>(eBoundSize))
0508   {
0509     constexpr std::size_t measdim =
0510         static_cast<std::size_t>(val_t::RowsAtCompileTime);
0511     derived().allocateCalibrated(measdim);
0512     calibrated<measdim>() = val;
0513     calibratedCovariance<measdim>() = cov;
0514   }
0515 };
0516
0517 }  // namespace Acts