Skip to content

Commit

Permalink
docs: Track EDM doxygen comment updates (#2816)
Browse files Browse the repository at this point in the history 
This is pulled out of #2797 and includes only the doxygen comment changes.

Blocked by:
- #2712
- #2817 
- #2807
  • Loading branch information
@paulgessinger
paulgessinger authored Dec 18, 2023
1 parent 858a48a commit ba0ab93
Show file tree
Hide file tree
Showing 11 changed files with 983 additions and 621 deletions.
170 changes: 100 additions & 70 deletions Core/include/Acts/EventData/MultiTrajectory.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -148,29 +148,34 @@ struct IsReadOnlyMultiTrajectory;
/// iterating over specific sub-components.
template <typename derived_t>
class MultiTrajectory {
public:
using Derived = derived_t;

static constexpr bool ReadOnly = IsReadOnlyMultiTrajectory<Derived>::value;

// Pull out type alias and re-expose them for ease of use.
//
static constexpr unsigned int MeasurementSizeMax =
MultiTrajectoryTraits::MeasurementSizeMax;

private:
friend class TrackStateProxy<Derived, MeasurementSizeMax, true>;
friend class TrackStateProxy<Derived, MeasurementSizeMax, false>;
template <typename T>
friend class MultiTrajectory;

public:
/// Alias for the const version of a track state proxy, with the same
/// backends as this container
using ConstTrackStateProxy =
Acts::TrackStateProxy<Derived, MeasurementSizeMax, true>;

/// Alias for the mutable version of a track state proxy, with the same
/// backends as this container
using TrackStateProxy =
Acts::TrackStateProxy<Derived, MeasurementSizeMax, false>;

/// The index type of the track state container
using IndexType = typename TrackStateProxy::IndexType;

/// Sentinel value that indicates an invalid index
static constexpr IndexType kInvalid = TrackStateProxy::kInvalid;

protected:
Expand Down Expand Up @@ -202,21 +207,45 @@ class MultiTrajectory {
}

public:
/// @anchor track_state_container_track_access
/// @name MultiTrajectory track state (proxy) access and manipulation
///
/// These methods allow accessing track states, i.e. adding or retrieving a
/// track state proxy that points at a specific track state in the container.
///
/// @{

/// Access a read-only point on the trajectory by index.
/// @note Only available if the MultiTrajectory is not read-only
/// @param istate The index to access
/// @return Read only proxy to the stored track state
ConstTrackStateProxy getTrackState(IndexType istate) const {
return {*this, istate};
}

/// Access a writable point on the trajectory by index.
/// @note Only available if the MultiTrajectory is not read-only
/// @param istate The index to access
/// @return Read-write proxy to the stored track state
template <bool RO = ReadOnly, typename = std::enable_if_t<!RO>>
TrackStateProxy getTrackState(IndexType istate) {
return {*this, istate};
}

/// Add a track state without providing explicit information. Which components
/// of the track state are initialized/allocated can be controlled via @p mask
/// @note Only available if the MultiTrajectory is not read-only
/// @param mask The bitmask that instructs which components to allocate and
/// which to leave invalid
/// @param iprevious index of the previous state, kInvalid if first
/// @return Index of the newly added track state
template <bool RO = ReadOnly, typename = std::enable_if_t<!RO>>
constexpr IndexType addTrackState(
TrackStatePropMask mask = TrackStatePropMask::All,
IndexType iprevious = kInvalid) {
return self().addTrackState_impl(mask, iprevious);
}

/// Add a track state to the container and return a track state proxy to it
/// This effectively calls @c addTrackState and @c getTrackState
/// @note Only available if the track state container is not read-only
Expand All @@ -228,13 +257,58 @@ class MultiTrajectory {
return getTrackState(addTrackState(mask, iprevious));
}

/// @}

/// @anchor track_state_container_iteration
/// @name MultiTrajectory track state iteration
/// @{

/// Visit all previous states starting at a given endpoint.
///
/// @param iendpoint index of the last state
/// @param callable non-modifying functor to be called with each point
template <typename F>
void visitBackwards(IndexType iendpoint, F&& callable) const;

/// Apply a function to all previous states starting at a given endpoint.
///
/// @param iendpoint index of the last state
/// @param callable modifying functor to be called with each point
///
/// @warning If the trajectory contains multiple components with common
/// points, this can have an impact on the other components.
/// @note Only available if the MultiTrajectory is not read-only
template <typename F, bool RO = ReadOnly, typename = std::enable_if_t<!RO>>
void applyBackwards(IndexType iendpoint, F&& callable) {
static_assert(detail_lt::VisitorConcept<F, TrackStateProxy>,
"Callable needs to satisfy VisitorConcept");

if (iendpoint == MultiTrajectoryTraits::kInvalid) {
throw std::runtime_error(
"Cannot apply backwards with kInvalid as endpoint");
}

while (true) {
auto ts = getTrackState(iendpoint);
if constexpr (std::is_same_v<std::invoke_result_t<F, TrackStateProxy>,
bool>) {
bool proceed = callable(ts);
// this point has no parent and ends the trajectory, or a break was
// requested
if (!proceed || !ts.hasPrevious()) {
break;
}
} else {
callable(ts);
// this point has no parent and ends the trajectory
if (!ts.hasPrevious()) {
break;
}
}
iendpoint = ts.previous();
}
}

/// Range for the track states from @p iendpoint to the trajectory start
/// @param iendpoint Trajectory entry point to start from
/// @return Iterator pair to iterate over
Expand All @@ -251,6 +325,7 @@ class MultiTrajectory {

/// Range for the track states from @p iendpoint to the trajectory start,
/// i.e from the outside in.
/// @note Only available if the MultiTrajectory is not read-only
/// @param iendpoint Trajectory entry point to start from
/// @return Iterator pair to iterate over
/// @note Mutable version
Expand Down Expand Up @@ -283,6 +358,7 @@ class MultiTrajectory {

/// Range for the track states from @p istartpoint to the trajectory end,
/// i.e from inside out
/// @note Only available if the MultiTrajectory is not read-only
/// @param istartpoint Trajectory state index for the innermost track
/// state to start from
/// @return Iterator pair to iterate over
Expand All @@ -297,79 +373,20 @@ class MultiTrajectory {
return range_t{getTrackState(istartpoint)};
}

/// Apply a function to all previous states starting at a given endpoint.
///
/// @param iendpoint index of the last state
/// @param callable modifying functor to be called with each point
///
/// @warning If the trajectory contains multiple components with common
/// points, this can have an impact on the other components.
template <typename F, bool RO = ReadOnly, typename = std::enable_if_t<!RO>>
void applyBackwards(IndexType iendpoint, F&& callable) {
static_assert(detail_lt::VisitorConcept<F, TrackStateProxy>,
"Callable needs to satisfy VisitorConcept");

if (iendpoint == MultiTrajectoryTraits::kInvalid) {
throw std::runtime_error(
"Cannot apply backwards with kInvalid as endpoint");
}

while (true) {
auto ts = getTrackState(iendpoint);
if constexpr (std::is_same_v<std::invoke_result_t<F, TrackStateProxy>,
bool>) {
bool proceed = callable(ts);
// this point has no parent and ends the trajectory, or a break was
// requested
if (!proceed || !ts.hasPrevious()) {
break;
}
} else {
callable(ts);
// this point has no parent and ends the trajectory
if (!ts.hasPrevious()) {
break;
}
}
iendpoint = ts.previous();
}
}

auto&& convertToReadOnly() const {
auto&& cv = self().convertToReadOnly_impl();
static_assert(
IsReadOnlyMultiTrajectory<decltype(cv)>::value,
"convertToReadOnly_impl does not return something that reports "
"being ReadOnly.");
return cv;
}

/// Clear the @c MultiTrajectory. Leaves the underlying storage untouched
template <bool RO = ReadOnly, typename = std::enable_if_t<!RO>>
constexpr void clear() {
self().clear_impl();
}

/// Returns the number of track states contained
constexpr IndexType size() const { return self().size_impl(); }
/// @}

/// Add a track state without providing explicit information. Which components
/// of the track state are initialized/allocated can be controlled via @p mask
/// @param mask The bitmask that instructs which components to allocate and
/// which to leave invalid
/// @param iprevious index of the previous state, kInvalid if first
/// @return Index of the newly added track state
template <bool RO = ReadOnly, typename = std::enable_if_t<!RO>>
constexpr IndexType addTrackState(
TrackStatePropMask mask = TrackStatePropMask::All,
IndexType iprevious = kInvalid) {
return self().addTrackState_impl(mask, iprevious);
}
/// @anchor track_state_container_columns
/// @name MultiTrajectory column management
/// MultiTrajectory can manage a set of common static columns, and dynamic
/// columns that can be added at runtime. This set of methods allows you to
/// manage the dynamic columns.
/// @{

/// Add a column to the @c MultiTrajectory
/// @tparam T Type of the column values to add
/// @note This takes a string argument rather than a hashed string to maintain
/// compatibility with backends.
/// @note Only available if the MultiTrajectory is not read-only
template <typename T, bool RO = ReadOnly, typename = std::enable_if_t<!RO>>
constexpr void addColumn(const std::string& key) {
self().template addColumn_impl<T>(key);
Expand All @@ -382,6 +399,19 @@ class MultiTrajectory {
return self().hasColumn_impl(key);
}

/// @}

/// Clear the @c MultiTrajectory. Leaves the underlying storage untouched
/// @note Only available if the MultiTrajectory is not read-only
template <bool RO = ReadOnly, typename = std::enable_if_t<!RO>>
constexpr void clear() {
self().clear_impl();
}

/// Returns the number of track states contained
/// @return The number of track states
constexpr IndexType size() const { return self().size_impl(); }

protected:
// These are internal helper functions which the @c TrackStateProxy class talks to

Expand Down
Loading

0 comments on commit ba0ab93

Please sign in to comment.