Acts/Seeding/SeedFinder.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/Definitions/Units.hpp"
0012 #include "Acts/EventData/SpacePointData.hpp"
0013 #include "Acts/Geometry/Extent.hpp"
0014 #include "Acts/Seeding/CandidatesForMiddleSp.hpp"
0015 #include "Acts/Seeding/InternalSeed.hpp"
0016 #include "Acts/Seeding/InternalSpacePoint.hpp"
0017 #include "Acts/Seeding/Neighbour.hpp"
0018 #include "Acts/Seeding/SeedFilter.hpp"
0019 #include "Acts/Seeding/SeedFinderConfig.hpp"
0020 #include "Acts/Seeding/SeedFinderUtils.hpp"
0021
0022 #include <array>
0023 #include <limits>
0024 #include <list>
0025 #include <map>
0026 #include <memory>
0027 #include <set>
0028 #include <string>
0029 #include <utility>
0030 #include <vector>
0031
0032 namespace Acts {
0033
0034 enum class SpacePointCandidateType : short { eBottom, eTop };
0035
0036 enum class DetectorMeasurementInfo : short { eDefault, eDetailed };
0037
0038 template <typename external_spacepoint_t, typename grid_t,
0039           typename platform_t = void*>
0040 class SeedFinder {
0041   ///////////////////////////////////////////////////////////////////
0042   // Public methods:
0043   ///////////////////////////////////////////////////////////////////
0044
0045  public:
0046   struct SeedingState {
0047     // bottom space point
0048     std::vector<InternalSpacePoint<external_spacepoint_t>*> compatBottomSP;
0049     std::vector<InternalSpacePoint<external_spacepoint_t>*> compatTopSP;
0050     // contains parameters required to calculate circle with linear equation
0051     // ...for bottom-middle
0052     std::vector<LinCircle> linCircleBottom;
0053     // ...for middle-top
0054     std::vector<LinCircle> linCircleTop;
0055
0056     // create vectors here to avoid reallocation in each loop
0057     std::vector<const InternalSpacePoint<external_spacepoint_t>*> topSpVec;
0058     std::vector<float> curvatures;
0059     std::vector<float> impactParameters;
0060
0061     // managing seed candidates for SpM
0062     CandidatesForMiddleSp<const InternalSpacePoint<external_spacepoint_t>>
0063         candidates_collector;
0064
0065     // managing doublet candidates
0066     boost::container::small_vector<Acts::Neighbour<grid_t>,
0067                                    Acts::detail::ipow(3, grid_t::DIM)>
0068         bottomNeighbours;
0069     boost::container::small_vector<Acts::Neighbour<grid_t>,
0070                                    Acts::detail::ipow(3, grid_t::DIM)>
0071         topNeighbours;
0072
0073     // Adding space point info
0074     Acts::SpacePointData spacePointData;
0075   };
0076
0077   /// The only constructor. Requires a config object.
0078   /// @param config the configuration for the SeedFinder
0079   SeedFinder(const Acts::SeedFinderConfig<external_spacepoint_t>& config);
0080   ~SeedFinder() = default;
0081   /**    @name Disallow default instantiation, copy, assignment */
0082   //@{
0083   SeedFinder() = default;
0084   SeedFinder(const SeedFinder<external_spacepoint_t, grid_t, platform_t>&) =
0085       delete;
0086   SeedFinder<external_spacepoint_t, grid_t, platform_t>& operator=(
0087       const SeedFinder<external_spacepoint_t, grid_t, platform_t>&) = default;
0088   //@}
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 outIt Output iterator 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 <template <typename...> typename container_t, typename sp_range_t>
0103   void createSeedsForGroup(
0104       const Acts::SeedFinderOptions& options, SeedingState& state,
0105       const grid_t& grid,
0106       std::back_insert_iterator<container_t<Seed<external_spacepoint_t>>> outIt,
0107       const sp_range_t& bottomSPs, const std::size_t middleSPs,
0108       const sp_range_t& topSPs,
0109       const Acts::Range1D<float>& rMiddleSPRange) const;
0110
0111   /// @brief Compatibility method for the new-style seed finding API.
0112   ///
0113   /// This method models the old-style seeding API where we only need a
0114   /// container for the bottom, middle, and top space points. Also, the results
0115   /// are returned by value instead of inserted into an inserter.
0116   ///
0117   /// @note This method is a very simply wrapper around the more modern API.
0118   /// @warning The performance of the seeding code is far greater if the new
0119   /// API is used, and this is recommended for all new uses which do not
0120   /// require backwards-compatibility.
0121   ///
0122   /// @tparam sp_range_t container type for the seed point collections.
0123   /// @param options frequently changing configuration (like beam position)
0124   /// @param grid The grid with space points
0125   /// @param bottomSPs group of space points to be used as innermost SP in a
0126   /// seed.
0127   /// @param middleSPs group of space points to be used as middle SP in a seed.
0128   /// @param topSPs group of space points to be used as outermost SP in a seed.
0129   /// @returns a vector of seeds.
0130   template <typename sp_range_t>
0131   std::vector<Seed<external_spacepoint_t>> createSeedsForGroup(
0132       const Acts::SeedFinderOptions& options, const grid_t& grid,
0133       const sp_range_t& bottomSPs, const std::size_t middleSPs,
0134       const sp_range_t& topSPs) const;
0135
0136  private:
0137   /// Iterates over dublets and tests the compatibility between them by applying
0138   /// a series of cuts that can be tested with only two SPs
0139   /// @param spacePointData object containing the spacepoint data
0140   /// @param options frequently changing configuration (like beam position)
0141   /// @param grid spacepoint grid
0142   /// @param otherSPsNeighbours inner or outer space points to be used in the dublet
0143   /// @param mediumSP space point candidate to be used as middle SP in a seed
0144   /// @param linCircleVec vector containing inner or outer SP parameters after reference frame transformation to the u-v space
0145   /// @param outVec Output object containing top or bottom SPs that are compatible with a certain middle SPs
0146   /// @param deltaRMinSP minimum allowed r-distance between dublet components
0147   /// @param deltaRMaxSP maximum allowed r-distance between dublet components
0148   /// @param uIP minus one over radius of middle SP
0149   /// @param uIP2 square of uIP
0150   /// @param cosPhiM ratio between middle SP x position and radius
0151   /// @param sinPhiM ratio between middle SP y position and radius
0152   template <Acts::SpacePointCandidateType candidateType, typename out_range_t>
0153   void getCompatibleDoublets(
0154       Acts::SpacePointData& spacePointData,
0155       const Acts::SeedFinderOptions& options, const grid_t& grid,
0156       boost::container::small_vector<Acts::Neighbour<grid_t>,
0157                                      Acts::detail::ipow(3, grid_t::DIM)>&
0158           otherSPsNeighbours,
0159       const InternalSpacePoint<external_spacepoint_t>& mediumSP,
0160       std::vector<LinCircle>& linCircleVec, out_range_t& outVec,
0161       const float deltaRMinSP, const float deltaRMaxSP, const float uIP,
0162       const float uIP2, const float cosPhiM, const float sinPhiM) const;
0163
0164   /// Iterates over the seed candidates tests the compatibility between three
0165   /// SPs and calls for the seed confirmation
0166   /// @param spacePointData object containing the spacepoint data
0167   /// @param SpM space point candidate to be used as middle SP in a seed
0168   /// @param options frequently changing configuration (like beam position)
0169   /// @param seedFilterState State object that holds memory used in SeedFilter
0170   /// @param state State object that holds memory used
0171   template <Acts::DetectorMeasurementInfo detailedMeasurement>
0172   void filterCandidates(Acts::SpacePointData& spacePointData,
0173                         const InternalSpacePoint<external_spacepoint_t>& SpM,
0174                         const Acts::SeedFinderOptions& options,
0175                         SeedFilterState& seedFilterState,
0176                         SeedingState& state) const;
0177
0178  private:
0179   Acts::SeedFinderConfig<external_spacepoint_t> m_config;
0180 };
0181
0182 }  // namespace Acts
0183
0184 #ifndef DOXYGEN
0185 #include "Acts/Seeding/SeedFinder.ipp"
0186 #endif