Acts/Utilities/GridBinFinder.hpp

0001 // This file is part of the Acts project.
0002 //
0003 // Copyright (C) 2024 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 http://mozilla.org/MPL/2.0/.
0008
0009 #pragma once
0010
0011 #include "Acts/Utilities/Grid.hpp"
0012 #include "Acts/Utilities/Holders.hpp"
0013 #include "Acts/Utilities/detail/grid_helper.hpp"
0014
0015 #include <variant>
0016 #include <vector>
0017
0018 #include <boost/container/small_vector.hpp>
0019
0020 namespace Acts {
0021
0022 /// @class BinFinder
0023 /// @tparam DIM Dimension of the Grid on which the GridBinFinder will be used
0024 ///
0025 /// The BinFinder is used by the ISPGroupSelector. It can be
0026 /// used to find both bins that could be bottom bins as well as bins that could
0027 /// be top bins, which are assumed to be the same bins. Does not take
0028 /// interaction region into account to limit z-bins.
0029 template <std::size_t DIM>
0030 class GridBinFinder {
0031  public:
0032   /// @brief Constructor
0033   /// @tparam args ... Input parameters provided by the user
0034   ///
0035   /// @param [in] vals The input parameters that define how many neighbours we need to find
0036   ///
0037   /// @pre The provided paramers must be of type 'int', 'std::pair<int, int>' or 'std::vector<std::pair<int, int>>'
0038   /// no other type is allowed. The order of these parameters must correspond to
0039   /// the same ordering of the axes in the grid
0040   template <typename... args>
0041   GridBinFinder(args&&... vals);
0042
0043   /// @brief Retrieve the neighbouring bins given a local position in the grid
0044   ///
0045   /// Return all bins that could contain space points that can be used with the
0046   /// space points in the bin with the provided indices to create seeds.
0047   ///
0048   /// @tparam stored_t The type of elements stored in the Grid
0049   /// @tparam Axes ... The type of the axes of the grid
0050   ///
0051   /// @param [in] locPosition The N-dimentional local position in the grid
0052   /// @param [in] grid The grid
0053   /// @return The list of neighbouring bins
0054   ///
0055   /// @pre The provided local position must be a valid local bins configuration in the grid
0056   template <typename stored_t, class... Axes>
0057   boost::container::small_vector<std::size_t, Acts::detail::ipow(3, DIM)>
0058   findBins(const std::array<std::size_t, DIM>& locPosition,
0059            const Acts::Grid<stored_t, Axes...>& grid) const;
0060
0061  private:
0062   /// @brief Store the values provided by the user for each axis in the grid
0063   /// @tparam first_value_t Type of the first value
0064   /// @tparam vals ... values of the remaining values
0065   ///
0066   /// @param [in] fv The first value in the list
0067   /// @param [in] others The remaining values in the list
0068   ///
0069   /// @pre both first_value_t and vals ... can be only int or std::vector<std::pair<int, int>>
0070   /// In the second case, the number of entries of the vector of pairs MUST be
0071   /// equal to the number of bins in that specific axis. Empty vectors are also
0072   /// allowed but in this case the value will be replaced with a 1 (integer),
0073   /// thus instructing the code to look for neighbours in the range {-1 ,1}
0074   template <typename first_value_t, typename... vals>
0075   void storeValue(first_value_t&& fv, vals&&... others);
0076
0077   /// @brief Get the instructions for retrieving the neighbouring bins given a local position
0078   ///
0079   /// @param [in] locPosition The requested local position
0080   /// @return the instructions for retrieving the neighbouring bins for this local position
0081   ///
0082   /// @pre The local position must be a valid local bins configuration for the grid
0083   std::array<std::pair<int, int>, DIM> getSizePerAxis(
0084       const std::array<std::size_t, DIM>& locPosition) const;
0085
0086   /// @brief Check the GridBinFinder configuration is compatible with the grid
0087   /// by checking the values of m_values against the axes of the grid
0088   /// This function is called only in debug mode
0089   ///
0090   /// @tparam stored_t The type of elements stored in the Grid
0091   /// @tparam Axes ... The type of the axes of the grid
0092   ///
0093   /// @param [in] grid The Grid
0094   /// @return If the GridBinFinder is compatible with the grid
0095   template <typename stored_t, class... Axes>
0096   bool isGridCompatible(const Acts::Grid<stored_t, Axes...>& grid) const;
0097
0098  private:
0099   using stored_values_t =
0100       std::variant<int, std::pair<int, int>, std::vector<std::pair<int, int>>>;
0101   /// @brief the instructions for retrieving the nieghbouring bins for each given axis in the grid
0102   /// These values are provided by the user and can be ints, a pair of ints or a
0103   /// vector of pair of ints. In the first case, the neighbours will be +/- bins
0104   /// from the given local bin In the second case, the user defines how many
0105   /// bins in both directions should be provided
0106   ///
0107   /// @pre The list of entries of the vector of pairs MUST be equal to the number of bins in that specific
0108   /// axis. Empty vectors are also allowed  but in this case the value will be
0109   /// replaced with a 1 (integer), thus instructing the code to look for
0110   /// neighbours in the range {-1 ,1}
0111   std::array<stored_values_t, DIM> m_values{};
0112 };
0113
0114 }  // namespace Acts
0115 #include "Acts/Utilities/GridBinFinder.ipp"