Acts/Seeding/SeedFinder.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/Definitions/Units.hpp"
0012 #include "Acts/EventData/SpacePointMutableData.hpp"
0013 #include "Acts/Geometry/Extent.hpp"
0014 #include "Acts/Seeding/CandidatesForMiddleSp.hpp"
0015 #include "Acts/Seeding/Neighbour.hpp"
0016 #include "Acts/Seeding/SeedFilter.hpp"
0017 #include "Acts/Seeding/SeedFinderConfig.hpp"
0018 #include "Acts/Seeding/SeedFinderUtils.hpp"
0019 #include "Acts/Seeding/SpacePointGrid.hpp"
0020 #include "Acts/Seeding/detail/UtilityFunctions.hpp"
0021 #include "Acts/Utilities/Logger.hpp"
0022
0023 #include <array>
0024 #include <limits>
0025 #include <list>
0026 #include <map>
0027 #include <memory>
0028 #include <ranges>
0029 #include <set>
0030 #include <string>
0031 #include <utility>
0032 #include <vector>
0033
0034 namespace Acts {
0035
0036 template <typename Coll>
0037 concept GridBinCollection =
0038     std::ranges::random_access_range<Coll> &&
0039     std::same_as<typename Coll::value_type, std::size_t>;
0040
0041 template <typename collection_t, typename external_t, std::size_t N = 3ul>
0042 concept CollectionStoresSeedsTo =
0043     requires(collection_t coll, Acts::Seed<external_t, N> seed) {
0044       Acts::detail::pushBackOrInsertAtEnd(coll, seed);
0045     };
0046
0047 enum class SpacePointCandidateType : short { eBottom, eTop };
0048
0049 enum class DetectorMeasurementInfo : short { eDefault, eDetailed };
0050
0051 template <typename external_spacepoint_t, typename grid_t,
0052           typename platform_t = void*>
0053 class SeedFinder {
0054   ///////////////////////////////////////////////////////////////////
0055   // Public methods:
0056   ///////////////////////////////////////////////////////////////////
0057
0058  public:
0059   struct SeedingState {
0060     // bottom space point
0061     std::vector<const external_spacepoint_t*> compatBottomSP{};
0062     std::vector<const external_spacepoint_t*> compatTopSP{};
0063     // contains parameters required to calculate circle with linear equation
0064     // ...for bottom-middle
0065     std::vector<LinCircle> linCircleBottom{};
0066     // ...for middle-top
0067     std::vector<LinCircle> linCircleTop{};
0068
0069     // create vectors here to avoid reallocation in each loop
0070     std::vector<const external_spacepoint_t*> topSpVec{};
0071     std::vector<float> curvatures{};
0072     std::vector<float> impactParameters{};
0073
0074     // managing seed candidates for SpM
0075     CandidatesForMiddleSp<const external_spacepoint_t> candidates_collector{};
0076
0077     // managing doublet candidates
0078     boost::container::small_vector<Acts::Neighbour<grid_t>,
0079                                    Acts::detail::ipow(3, grid_t::DIM)>
0080         bottomNeighbours{};
0081     boost::container::small_vector<Acts::Neighbour<grid_t>,
0082                                    Acts::detail::ipow(3, grid_t::DIM)>
0083         topNeighbours{};
0084
0085     // Mutable variables for Space points used in the seeding
0086     Acts::SpacePointMutableData spacePointMutableData{};
0087   };
0088
0089   /// The only constructor. Requires a config object.
0090   /// @param config the configuration for the SeedFinder
0091   /// @param logger the ACTS logger
0092   SeedFinder(const Acts::SeedFinderConfig<external_spacepoint_t>& config,
0093              std::unique_ptr<const Acts::Logger> logger =
0094                  getDefaultLogger("Finder", Logging::Level::INFO));
0095   SeedFinder(SeedFinder<external_spacepoint_t, grid_t, platform_t>&&) noexcept =
0096       default;
0097   SeedFinder& operator=(SeedFinder<external_spacepoint_t, grid_t,
0098                                    platform_t>&&) noexcept = default;
0099   ~SeedFinder() = default;
0100   /**    @name Disallow default instantiation, copy, assignment */
0101   //@{
0102   SeedFinder() = default;
0103   SeedFinder(const SeedFinder<external_spacepoint_t, grid_t, platform_t>&) =
0104       delete;
0105   SeedFinder<external_spacepoint_t, grid_t, platform_t>& operator=(
0106       const SeedFinder<external_spacepoint_t, grid_t, platform_t>&) = delete;
0107   //@}
0108
0109   /// Create all seeds from the space points in the three iterators.
0110   /// Can be used to parallelize the seed creation
0111   /// @param options frequently changing configuration (like beam position)
0112   /// @param state State object that holds memory used
0113   /// @param grid The grid with space points
0114   /// @param outputCollection Output container for the seeds in the group
0115   /// @param bottomSPs group of space points to be used as innermost SP in a seed.
0116   /// @param middleSPs group of space points to be used as middle SP in a seed.
0117   /// @param topSPs group of space points to be used as outermost SP in a seed.
0118   /// @param rMiddleSPRange range object containing the minimum and maximum r for middle SP for a certain z bin.
0119   /// @note Ranges must return pointers.
0120   /// @note Ranges must be separate objects for each parallel call.
0121   template <typename container_t, Acts::GridBinCollection sp_range_t>
0122     requires Acts::CollectionStoresSeedsTo<container_t, external_spacepoint_t,
0123                                            3ul>
0124   void createSeedsForGroup(const Acts::SeedFinderOptions& options,
0125                            SeedingState& state, const grid_t& grid,
0126                            container_t& outputCollection,
0127                            const sp_range_t& bottomSPs,
0128                            const std::size_t middleSPs,
0129                            const sp_range_t& topSPs,
0130                            const Acts::Range1D<float>& rMiddleSPRange) const;
0131
0132  private:
0133   /// Given a middle space point candidate, get the proper radius validity range
0134   /// In case the radius range changes according to the z-bin we need to
0135   /// retrieve the proper range. We can do this computation only once, since
0136   /// all the middle space point candidates belong to the same z-bin
0137   /// @param spM space point candidate to be used as middle SP in a seed
0138   /// @param rMiddleSPRange range object containing the minimum and maximum r for middle SP for a certain z bin.
0139   std::pair<float, float> retrieveRadiusRangeForMiddle(
0140       const external_spacepoint_t& spM,
0141       const Acts::Range1D<float>& rMiddleSPRange) const;
0142
0143   /// Iterates over dublets and tests the compatibility between them by applying
0144   /// a series of cuts that can be tested with only two SPs
0145   /// @param options frequently changing configuration (like beam position)
0146   /// @param grid spacepoint grid
0147   /// @param mutableData Container for mutable variables used in the seeding
0148   /// @param otherSPsNeighbours inner or outer space points to be used in the dublet
0149   /// @param mediumSP space point candidate to be used as middle SP in a seed
0150   /// @param linCircleVec vector containing inner or outer SP parameters after reference frame transformation to the u-v space
0151   /// @param outVec Output object containing top or bottom SPs that are compatible with a certain middle SPs
0152   /// @param deltaRMinSP minimum allowed r-distance between dublet components
0153   /// @param deltaRMaxSP maximum allowed r-distance between dublet components
0154   /// @param uIP minus one over radius of middle SP
0155   /// @param uIP2 square of uIP
0156   /// @param cosPhiM ratio between middle SP x position and radius
0157   /// @param sinPhiM ratio between middle SP y position and radius
0158   template <Acts::SpacePointCandidateType candidateType, typename out_range_t>
0159   void getCompatibleDoublets(
0160       const Acts::SeedFinderOptions& options, const grid_t& grid,
0161       Acts::SpacePointMutableData& mutableData,
0162       boost::container::small_vector<Neighbour<grid_t>,
0163                                      Acts::detail::ipow(3, grid_t::DIM)>&
0164           otherSPsNeighbours,
0165       const external_spacepoint_t& mediumSP,
0166       std::vector<LinCircle>& linCircleVec, out_range_t& outVec,
0167       const float deltaRMinSP, const float deltaRMaxSP, const float uIP,
0168       const float uIP2, const float cosPhiM, const float sinPhiM) const;
0169
0170   /// Iterates over the seed candidates tests the compatibility between three
0171   /// SPs and calls for the seed confirmation
0172   /// @param SpM space point candidate to be used as middle SP in a seed
0173   /// @param options frequently changing configuration (like beam position)
0174   /// @param seedFilterState State object that holds memory used in SeedFilter
0175   /// @param state State object that holds memory used
0176   template <Acts::DetectorMeasurementInfo detailedMeasurement>
0177   void filterCandidates(const external_spacepoint_t& SpM,
0178                         const Acts::SeedFinderOptions& options,
0179                         SeedFilterState& seedFilterState,
0180                         SeedingState& state) const;
0181
0182  private:
0183   const Logger& logger() const { return *m_logger; }
0184
0185   Acts::SeedFinderConfig<external_spacepoint_t> m_config;
0186   std::unique_ptr<const Acts::Logger> m_logger{nullptr};
0187 };
0188
0189 }  // namespace Acts
0190
0191 #ifndef DOXYGEN
0192 #include "Acts/Seeding/SeedFinder.ipp"
0193 #endif