refactor!: General binned group for seeding

Core/include/Acts/Seeding/BinnedGroup.hpp

@@ -0,0 +1,102 @@
+// This file is part of the Acts project.
+//
+// Copyright (C) 2024 CERN for the benefit of the Acts project
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+#pragma once
+
+#include "Acts/Seeding/BinnedGroupIterator.hpp"
+#include "Acts/Seeding/SpacePointGrid.hpp"
+#include "Acts/Utilities/GridBinFinder.hpp"
+#include "Acts/Utilities/GridIterator.hpp"
+#include "Acts/Utilities/Holders.hpp"
+
+#include <memory>
+#include <vector>
+
+namespace Acts {
+
+/// @class BinnedGroup
+/// @tparam grid_t Type of the grid the group owns
+///
+/// The assumption is that the grid has ownership of the space points and
+/// that the grid value_type (i.e. T in Grid<T, Axes ...>) is an iterable
+/// object of space points, such as a vector< ... >
+template <typename grid_t>
+class BinnedGroup {
+ public:
+  friend BinnedGroupIterator<grid_t>;
+
+  static constexpr std::size_t DIM = grid_t::DIM;
+
+  /// @brief Default constructor
+  BinnedGroup() = delete;
+
+  /// brief Constructor
+  BinnedGroup(grid_t&& grid, const Acts::GridBinFinder<DIM>& bottomFinder,
+              const Acts::GridBinFinder<DIM>& topFinder,
+              std::array<std::vector<std::size_t>, DIM> navigation =
+                  std::array<std::vector<std::size_t>, DIM>());
+
+  BinnedGroup(grid_t& grid, const Acts::GridBinFinder<DIM>& bottomFinder,
+              const Acts::GridBinFinder<DIM>& topFinder,
+              std::array<std::vector<std::size_t>, DIM> navigation =
+                  std::array<std::vector<std::size_t>, DIM>()) = delete;
+
+  /// @brief Copy constructor
+  /// @param [in] other The BinnedGroup to copy
+  BinnedGroup(const BinnedGroup<grid_t>& other) = delete;
+  /// @brief Copy assignment
+  /// @param [in] other The BinnedGroup to copy
+  /// @return The copied BinnedGroup
+  BinnedGroup<grid_t>& operator=(const BinnedGroup<grid_t>& other) = delete;
+
+  /// @brief Move Constructor
+  /// @param [in] other The BinnedGroup to move
+  BinnedGroup(BinnedGroup<grid_t>&& other) noexcept = default;
+  /// @brief Move Assignment
+  /// @param [in] other The BinnedGroup to move
+  /// @return The moved BinnedGroup
+  BinnedGroup<grid_t>& operator=(BinnedGroup<grid_t>&& other) noexcept =
+      default;
+
+  /// @brief Default destructor
+  ~BinnedGroup() = default;
+
+  /// @brief Retrieve const reference to the Grid
+  /// @return Const reference to the stored grid
+  const grid_t& grid() const;
+  /// @brief Retrieve mutable reference to the Grid
+  /// @return Mutable reference to the stored grid
+  grid_t& grid();
+
+  /// @brief Get the begin iterator
+  /// @return The iterator
+  Acts::BinnedGroupIterator<grid_t> begin() const;
+  /// @brief Get the end iterator
+  /// @return The iterator
+  Acts::BinnedGroupIterator<grid_t> end() const;
+
+ private:
+  /// @brief The N-dimentional grid
+  grid_t m_grid;
+  /// @brief The Grid Bin Finder for bottom candidates
+  const Acts::GridBinFinder<DIM>* m_bottomBinFinder{nullptr};
+  /// @brief The Grid Bin Finder for top candidates
+  const Acts::GridBinFinder<DIM>* m_topBinFinder{nullptr};
+  /// @brief Order of bins to loop over when searching for SPs
+  std::array<std::vector<std::size_t>, DIM> m_bins{};
+};
+
+}  // namespace Acts
+
+#include "Acts/Seeding/BinnedGroup.ipp"
+
+namespace Acts {
+template <typename external_spacepoint_t>
+using BinnedSPGroup =
+    Acts::BinnedGroup<Acts::SpacePointGrid<external_spacepoint_t>>;
+}

Core/include/Acts/Seeding/BinnedGroup.ipp

@@ -0,0 +1,59 @@
+// This file is part of the Acts project.
+//
+// Copyright (C) 2024 CERN for the benefit of the Acts project
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+namespace Acts {
+
+template <typename grid_t>
+BinnedGroup<grid_t>::BinnedGroup(
+    grid_t&& grid,
+    const Acts::GridBinFinder<Acts::BinnedGroup<grid_t>::DIM>& bottomFinder,
+    const Acts::GridBinFinder<Acts::BinnedGroup<grid_t>::DIM>& topFinder,
+    std::array<std::vector<std::size_t>, Acts::BinnedGroup<grid_t>::DIM>
+        navigation)
+    : m_grid(std::move(grid)),
+      m_bottomBinFinder(&bottomFinder),
+      m_topBinFinder(&topFinder),
+      m_bins(std::move(navigation)) {
+  /// If navigation is not defined for all axes, then we default that to a
+  /// std::iota from 1ul
+  std::array<std::size_t, DIM> numLocBins = m_grid.numLocalBins();
+  for (std::size_t i(0ul); i < DIM; ++i) {
+    if (!m_bins[i].empty()) {
+      continue;
+    }
+    m_bins[i].resize(numLocBins[i]);
+    std::iota(m_bins[i].begin(), m_bins[i].end(), 1ul);
+  }
+}
+
+template <typename grid_t>
+const grid_t& BinnedGroup<grid_t>::grid() const {
+  return m_grid;
+}
+
+template <typename grid_t>
+grid_t& BinnedGroup<grid_t>::grid() {
+  return m_grid;
+}
+
+template <typename grid_t>
+Acts::BinnedGroupIterator<grid_t> BinnedGroup<grid_t>::begin() const {
+  return Acts::BinnedGroupIterator<grid_t>(
+      *this, std::array<std::size_t, Acts::BinnedGroup<grid_t>::DIM>(), m_bins);
+}
+
+template <typename grid_t>
+Acts::BinnedGroupIterator<grid_t> BinnedGroup<grid_t>::end() const {
+  std::array<std::size_t, Acts::BinnedGroup<grid_t>::DIM> endline{};
+  for (std::size_t i(0ul); i < Acts::BinnedGroup<grid_t>::DIM; ++i) {
+    endline[i] = m_bins[i].size();
+  }
+  return Acts::BinnedGroupIterator<grid_t>(*this, endline, m_bins);
+}
+
+}  // namespace Acts

Core/include/Acts/Seeding/BinnedGroupIterator.hpp

@@ -0,0 +1,128 @@
+// This file is part of the Acts project.
+//
+// Copyright (C) 2024 CERN for the benefit of the Acts project
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+#pragma once
+
+#include "Acts/Seeding/SpacePointGrid.hpp"
+#include "Acts/Utilities/GridIterator.hpp"
+#include "Acts/Utilities/Holders.hpp"
+#include "Acts/Utilities/detail/grid_helper.hpp"
+
+#include <array>
+#include <memory>
+#include <tuple>
+
+#include <boost/container/small_vector.hpp>
+
+namespace Acts {
+template <typename grid_t>
+class BinnedGroup;
+
+template <typename grid_t>
+class BinnedGroupIterator {
+ public:
+  static constexpr std::size_t DIM = grid_t::DIM;
+
+  /// @brief Constructor
+  /// Never take the ownership of the group
+  ///
+  /// @param [in] group The group we are iterating on
+  /// @param [in] index Current local position in the grid
+  /// @param [in] navigation The navigation pattern in the grid
+  BinnedGroupIterator(
+      Acts::BinnedGroup<grid_t>&& group, std::array<std::size_t, DIM> index,
+      std::array<std::vector<std::size_t>, DIM> navigation) = delete;
+
+  /// @brief Constructor
+  /// Never take the ownership of the group
+  ///
+  /// @param [in] group The group we are iterating on
+  /// @param [in] index Current local position in the grid
+  /// @param [in] navigation The navigation pattern in the grid
+  BinnedGroupIterator(const Acts::BinnedGroup<grid_t>&& group,
+                      std::array<std::size_t, DIM> index,
+                      std::array<std::vector<std::size_t>, DIM> navigation) =
+      delete;
+
+  /// @brief Constructor
+  /// @param [in] group The group we are iterating on
+  /// @param [in] index Current local position in the grid
+  /// @param [in] navigation The navigation pattern in the grid
+  BinnedGroupIterator(const Acts::BinnedGroup<grid_t>& group,
+                      std::array<std::size_t, DIM> index,
+                      std::array<std::vector<std::size_t>, DIM> navigation);
+
+  /// Do not allow Copy operations
+
+  /// @brief Copy Constructor
+  /// @param [in] other The BinnedGroupIterator to copy
+  BinnedGroupIterator(const BinnedGroupIterator<grid_t>& other) = delete;
+  /// @brief Copy assignment
+  /// @param [in] other The BinnedGroupIterator to copy
+  /// @return The copied BinnedGroupIterator
+  BinnedGroupIterator<grid_t>& operator=(
+      const BinnedGroupIterator<grid_t>& other) = delete;
+
+  /// @brief Move Constructor
+  /// @param [in] other The BinnedGroupIterator to move
+  BinnedGroupIterator(BinnedGroupIterator<grid_t>&& other) noexcept = default;
+  /// @brief Move assignment
+  /// @param [in] other The BinnedGroupIterator to move
+  /// @return The moved BinnedGroupIterator
+  BinnedGroupIterator<grid_t>& operator=(BinnedGroupIterator&& other) noexcept =
+      default;
+
+  /// @brief Default Destructor
+  ~BinnedGroupIterator() = default;
+
+  /// @brief Equality operator
+  /// @param [in] other The BinnedGroupIterator we are comparing against this one
+  /// @return The result of the comparison
+  bool operator==(const BinnedGroupIterator<grid_t>& other) const;
+  /// @brief (In-)Equality operator
+  /// @param [in] other The BinnedGroupIterator we are comparing against this one
+  /// @return The result of the comparison
+  bool operator!=(const BinnedGroupIterator<grid_t>& other) const;
+
+  /// @brief Increment the iterator by one (pre)
+  /// @return The incremented iterator
+  BinnedGroupIterator<grid_t>& operator++();
+
+  /// @brief Return the current bin with the middle candidate, as well as all the
+  /// bins with the possible bottom and top candidates
+  ///
+  /// @return The collection of all the bins in the grid
+  std::tuple<boost::container::small_vector<std::size_t,
+                                            Acts::detail::ipow(3, grid_t::DIM)>,
+             std::size_t,
+             boost::container::small_vector<std::size_t,
+                                            Acts::detail::ipow(3, grid_t::DIM)>>
+  operator*() const;
+
+ private:
+  /// @brief Move to the next not-empty bin in the grid
+  void findNotEmptyBin();
+
+ private:
+  /// @brief The group that contains the grid and the bin finders
+  Acts::detail::RefHolder<const Acts::BinnedGroup<grid_t>> m_group{nullptr};
+  /// @brief Current N-dimentional grid iterator
+  typename grid_t::local_iterator_t m_gridItr;
+  /// @brief End iterator;
+  typename grid_t::local_iterator_t m_gridItrEnd;
+};
+
+}  // namespace Acts
+
+#include "Acts/Seeding/BinnedGroupIterator.ipp"
+
+namespace Acts {
+template <typename external_spacepoint_t>
+using BinnedSPGroupIterator =
+    BinnedGroupIterator<Acts::SpacePointGrid<external_spacepoint_t>>;
+}

Core/include/Acts/Seeding/BinnedGroupIterator.ipp

@@ -0,0 +1,90 @@
+// This file is part of the Acts project.
+//
+// Copyright (C) 2024 CERN for the benefit of the Acts project
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+// Binned SP Group Iterator
+
+template <typename grid_t>
+Acts::BinnedGroupIterator<grid_t>::BinnedGroupIterator(
+    const Acts::BinnedGroup<grid_t>& group,
+    std::array<std::size_t, Acts::BinnedGroupIterator<grid_t>::DIM> index,
+    std::array<std::vector<std::size_t>, Acts::BinnedGroupIterator<grid_t>::DIM>
+        navigation)
+    : m_group(group), m_gridItr(group.grid(), index, navigation) {
+  std::array<std::size_t, DIM> endline{};
+  for (std::size_t i(0ul); i < DIM; ++i) {
+    endline[i] = navigation[i].size();
+  }
+  m_gridItrEnd = typename grid_t::local_iterator_t(m_group->grid(), endline,
+                                                   std::move(navigation));
+  findNotEmptyBin();
+}
+
+template <typename grid_t>
+bool Acts::BinnedGroupIterator<grid_t>::operator==(
+    const Acts::BinnedGroupIterator<grid_t>& other) const {
+  return m_group.ptr == other.m_group.ptr && m_gridItr == other.m_gridItr;
+}
+
+template <typename grid_t>
+bool Acts::BinnedGroupIterator<grid_t>::operator!=(
+    const Acts::BinnedGroupIterator<grid_t>& other) const {
+  return !(*this == other);
+}
+
+template <typename grid_t>
+Acts::BinnedGroupIterator<grid_t>&
+Acts::BinnedGroupIterator<grid_t>::operator++() {
+  ++m_gridItr;
+  findNotEmptyBin();
+  return *this;
+}
+
+template <typename grid_t>
+std::tuple<boost::container::small_vector<std::size_t,
+                                          Acts::detail::ipow(3, grid_t::DIM)>,
+           std::size_t,
+           boost::container::small_vector<std::size_t,
+                                          Acts::detail::ipow(3, grid_t::DIM)>>
+Acts::BinnedGroupIterator<grid_t>::operator*() const {
+  /// Get the global and local position from current iterator. This is the bin
+  /// with the middle candidate And we know this is not an empty bin
+  std::array<std::size_t, DIM> localPosition = m_gridItr.localBinsIndices();
+  std::size_t global_index =
+      m_group->grid().globalBinFromLocalBins(localPosition);
+
+  /// Get the neighbouring bins
+  boost::container::small_vector<std::size_t, Acts::detail::ipow(3, DIM)>
+      bottoms =
+          m_group->m_bottomBinFinder->findBins(localPosition, m_group->grid());
+  boost::container::small_vector<std::size_t, Acts::detail::ipow(3, DIM)> tops =
+      m_group->m_topBinFinder->findBins(localPosition, m_group->grid());
+
+  // GCC12+ in Release throws an overread warning here due to the move.
+  // This is from inside boost code, so best we can do is to suppress it.
+#if defined(__GNUC__) && __GNUC__ >= 12 && !defined(__clang__)
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wstringop-overread"
+#endif
+  return std::make_tuple(std::move(bottoms), global_index, std::move(tops));
+#if defined(__GNUC__) && __GNUC__ >= 12 && !defined(__clang__)
+#pragma GCC diagnostic pop
+#endif
+}
+
+template <typename grid_t>
+void Acts::BinnedGroupIterator<grid_t>::findNotEmptyBin() {
+  if (m_gridItr == m_gridItrEnd) {
+    return;
+  }
+  /// Iterate on the grid till we find a not-empty bin
+  /// We start from the current bin configuration and move forward
+  std::size_t dimCollection = (*m_gridItr).size();
+  while (dimCollection == 0ul && ++m_gridItr != m_gridItrEnd) {
+    dimCollection = (*m_gridItr).size();
+  }
+}