traccc/clusterization/clustering_config.hpp

0001 /**
0002  * traccc library, part of the ACTS project (R&D line)
0003  *
0004  * (c) 2024 CERN for the benefit of the ACTS project
0005  *
0006  * Mozilla Public License Version 2.0
0007  */
0008
0009 #pragma once
0010
0011 #include <cstddef>
0012
0013 #include "traccc/definitions/qualifiers.hpp"
0014
0015 namespace traccc {
0016 /**
0017  * @brief The different strategies that can be used to compute the diameter
0018  * of a cluster.
0019  */
0020 enum class clustering_diameter_strategy {
0021   /**
0022    * @brief Compute the diameter as the size of the cluster in the channel0
0023    * dimension.
0024    */
0025   CHANNEL0,
0026   /**
0027    * @brief Compute the diameter as the size of the cluster in the channel1
0028    * dimension.
0029    */
0030   CHANNEL1,
0031   /**
0032    * @brief Compute the diameter as the maximum of the sizes of the cluster
0033    * in the channel0 and channel1 dimensions.
0034    */
0035   MAXIMUM,
0036   /**
0037    * @brief Compute the diameter as the diagonal (i.e. the hypotenuse) of
0038    * the triangle with sides bounding both the channel0 and channel1
0039    * dimensions.
0040    */
0041   DIAGONAL
0042 };
0043
0044 /**
0045  * @brief Configuration type for massively parallel clustering algorithms.
0046  */
0047 struct clustering_config {
0048   /**
0049    * @brief The desired number of threads per partition.
0050    *
0051    * This directly correlates to the block size on most algorithms, so don't
0052    * set this too low (which will reduce occupancy due to available thread
0053    * slots) or too high (which may not be supported on a device).
0054    */
0055   unsigned int threads_per_partition{256};
0056
0057   /**
0058    * @brief The maximum number of cells per thread.
0059    *
0060    * This sets the maximum thread coarsening factor for the CCA algorithm.
0061    * Increasing this value increases shared memory usage and may decrease
0062    * occupancy. If this is too low, scratch space will need to be used which
0063    * may slow the algorithm down.
0064    */
0065   unsigned int max_cells_per_thread{16};
0066
0067   /**
0068    * @brief The desired number of cells per thread.
0069    *
0070    * This sets the desired thread coarsening factor for the CCA algorithm.
0071    * Decreasing this may decrease occupancy. Increasing this increases the
0072    * probability that scratch space will need to be used.
0073    */
0074   unsigned int target_cells_per_thread{8};
0075
0076   /**
0077    * @brief The upscaling factor for the scratch space.
0078    *
0079    * The scratch space will be large enough to support partitions this number
0080    * of times larger than the maximum partition size determined by
0081    * `threads_per_partition` and `max_cells_per_thread`
0082    */
0083   unsigned int backup_size_multiplier{256};
0084
0085   /**
0086    * @brief The strategy for computing the cluster width.
0087    *
0088    * See the enum definition for more details.
0089    */
0090   clustering_diameter_strategy diameter_strategy =
0091       clustering_diameter_strategy::CHANNEL1;
0092
0093   /**
0094    * @brief Sort the cells before running
0095    */
0096   bool sort_cells = false;
0097
0098   /**
0099    * @brief The maximum number of cells per partition.
0100    */
0101   TRACCC_HOST_DEVICE constexpr unsigned int max_partition_size() const {
0102     return threads_per_partition * max_cells_per_thread;
0103   }
0104
0105   /**
0106    * @brief The target number of cells per partition.
0107    */
0108   TRACCC_HOST_DEVICE constexpr unsigned int target_partition_size() const {
0109     return threads_per_partition * target_cells_per_thread;
0110   }
0111
0112   /**
0113    * @brief The total size of the scratch space, in number of cells.
0114    */
0115   TRACCC_HOST_DEVICE constexpr unsigned int backup_size() const {
0116     return max_partition_size() * backup_size_multiplier;
0117   }
0118 };
0119 }  // namespace traccc