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