Back to home page

EIC code displayed by LXR

 
 

    


File indexing completed on 2026-11-20 09:47:05

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/Utilities/HashCombine.hpp"
0012 
0013 #include <array>
0014 #include <cstdint>
0015 #include <ostream>
0016 #include <span>
0017 #include <stdexcept>
0018 #include <string>
0019 
0020 namespace ActsFatras {
0021 
0022 /// Particle identifier that encodes additional event information.
0023 ///
0024 /// The barcode has to fulfill two separate requirements: be able to act as
0025 /// unique identifier for particles within an event and to encode details
0026 /// on the event structure for fast lookup. Since we only care about tracking
0027 /// here, we need to support two scenarios:
0028 ///
0029 /// *   Identify which primary/secondary vertex particles belong to. No
0030 ///     information on intermediate/unstable/invisible particles needs to be
0031 ///     retained. This information is already available in the underlying
0032 ///     generator event and should not be duplicated.
0033 /// *   If (visible) particles convert, decay, or interact with the detector,
0034 ///     we need to be able to identify the initial (primary) particle. Typical
0035 ///     examples are pion nuclear interactions or electron/gamma conversions.
0036 ///
0037 /// The vertex information is encoded as two numbers that define the
0038 /// primary and secondary vertex. The primary vertex must be non-zero.
0039 /// Particles with a zero secondary vertex originate directly from the primary
0040 /// vertex.
0041 ///
0042 /// Within one vertex (primary+secondary) each particle is identified by
0043 /// a particle, generation, and sub-particle number. Particles originating
0044 /// from the vertex must have zero generation and zero sub-particle number;
0045 /// a consequence is that only non-zero generation can have non-zero
0046 /// sub-particle numbers. A non-zero generation indicates that the particle
0047 /// is a descendant of the original particle, e.g. from interactions or decay,
0048 /// while the sub-particle number identifies the descendant particle.
0049 ///
0050 /// With this encoding, non-primary particles and their primary parent can
0051 /// be easily identified at the expense of not storing the exact decay history.
0052 ///
0053 /// A barcode with all elements set to zero (the default value) is an invalid
0054 /// value that can be used e.g. to mark missing or unknown particles.
0055 ///
0056 /// ## Example
0057 ///
0058 /// A particle generated in a primary interaction might have the barcode
0059 ///
0060 ///     2|0|14|0|0 -> vertex=2 (primary), particle=14, generation=0, sub=0
0061 ///
0062 /// A simulation module might generate an interaction and create two new
0063 /// particles. These are descendants of the initial particle and the simulation
0064 /// module can generate the new barcodes directly by increasing the
0065 /// generation number and choosing sub-particle identifiers:
0066 ///
0067 ///     2|0|14|1|0 -> vertex=2 (primary), particle=14, generation=1, sub=0
0068 ///     2|0|14|1|1 -> vertex=2 (primary), particle=14, generation=1, sub=1
0069 ///
0070 /// If these secondary particles generate further tertiary particles
0071 /// the barcode would be e.g.
0072 ///
0073 ///     2|0|14|2|0 -> vertex=2 (primary), particle=14, generation=2, sub=0
0074 ///
0075 /// ## Possible issues
0076 ///
0077 /// The hierarchical nature of the barcode allows barcode creation without
0078 /// a central service. Since the full history is not stored, generated barcodes
0079 /// for higher-generation particles can overlap when generated by independent
0080 /// interactions. Assuming an initial primary particle with barcode
0081 ///
0082 ///     3|4|5|0|0 -> particle=5
0083 ///
0084 /// a first interaction might create a secondary particle by increasing the
0085 /// generation number (without destroying the initial particle)
0086 ///
0087 ///     3|4|5|1|0 -> particle=5, generation+=1, first sub-particle
0088 ///
0089 /// The initial particle gets simulated further and at another step a second
0090 /// interaction also creates a new particle. Since it knows nothing about
0091 /// the previously created particle (no central service), it will generate
0092 ///
0093 ///     3|4|5|1|0 -> particle=5, generation+=1, first sub-particle
0094 ///
0095 /// which is identical to the previously create barcode. These cases can be
0096 /// easily solved by renumbering the sub-particle identifier within each
0097 /// generation to contain unique values. However, this can only be done when all
0098 /// particles are known.
0099 class Barcode {
0100  public:
0101   /// Identifier type for primary vertex
0102   using PrimaryVertexId = std::uint16_t;
0103   /// Identifier type for secondary vertex
0104   using SecondaryVertexId = std::uint16_t;
0105   /// Identifier type for particle
0106   using ParticleId = std::uint32_t;
0107   /// Identifier type for generation
0108   using GenerationId = std::uint8_t;
0109   /// Identifier type for sub-particle
0110   using SubParticleId = std::uint32_t;
0111 
0112   /// Construct an invalid barcode with all levels set to zero.
0113   /// @return An invalid barcode
0114   static constexpr Barcode Invalid() { return Barcode(); }
0115 
0116   /// Empty barcode
0117   constexpr Barcode() = default;
0118   /// Copy constructor
0119   constexpr Barcode(const Barcode&) = default;
0120   /// Move constructor
0121   constexpr Barcode(Barcode&&) = default;
0122   /// Copy assignment operator
0123   /// @return Reference to this barcode after copying
0124   Barcode& operator=(const Barcode&) = default;
0125   /// Move assignment operator
0126   /// @return Reference to this barcode after moving
0127   Barcode& operator=(Barcode&&) = default;
0128 
0129   ///  Compare two barcodes
0130   /// @return True if barcodes are equal
0131   bool operator==(const Barcode&) const = default;
0132   friend constexpr auto operator<=>(Barcode lhs, Barcode rhs) {
0133     return lhs.asArray() <=> rhs.asArray();
0134   }
0135 
0136   /// Check validity of the barcode
0137   /// @param b The barcode to check
0138   /// @return True if barcode is valid
0139   static constexpr bool isValid(const Barcode& b) { return b != Invalid(); }
0140   /// Check if this barcode is valid
0141   /// @return True if this barcode is valid
0142   constexpr bool isValid() const { return isValid(*this); }
0143 
0144   /// Return the primary vertex identifier.
0145   /// @return The primary vertex identifier value
0146   constexpr PrimaryVertexId vertexPrimary() const { return vertexPrimaryID; }
0147 
0148   /// Return the secondary vertex identifier.
0149   /// @return The secondary vertex identifier value
0150   constexpr SecondaryVertexId vertexSecondary() const {
0151     return vertexSecondaryID;
0152   }
0153 
0154   /// Return the particle identifier.
0155   /// @return The particle identifier value
0156   constexpr ParticleId particle() const { return particleID; }
0157 
0158   /// Return the generation identifier.
0159   /// @return The generation identifier value
0160   constexpr GenerationId generation() const { return generationID; }
0161 
0162   /// Return the sub-particle identifier.
0163   /// @return The sub-particle identifier value
0164   constexpr SubParticleId subParticle() const { return subParticleID; }
0165 
0166   /// Export barcode as array
0167   /// @return Array of barcode components
0168   constexpr std::array<std::uint32_t, 5> asArray() const {
0169     return {vertexPrimary(), vertexSecondary(), particle(), generation(),
0170             subParticle()};
0171   }
0172 
0173   /// @deprecated Use asArray() instead to avoid a heap allocation.
0174   /// @return Vector of barcode components
0175   [[deprecated("Use asArray() instead to avoid a heap allocation")]]
0176   std::vector<std::uint32_t> asVector() const {
0177     auto arr = asArray();
0178     return std::vector<std::uint32_t>(arr.begin(), arr.end());
0179   }
0180 
0181   /// Create a new barcode with a different primary vertex identifier.
0182   /// @param id Primary vertex identifier to set
0183   /// @return New barcode with modified primary vertex identifier
0184   [[nodiscard]]
0185   constexpr Barcode withVertexPrimary(PrimaryVertexId id) const {
0186     Barcode barcode = *this;
0187     barcode.vertexPrimaryID = id;
0188     return barcode;
0189   }
0190 
0191   /// Create a new barcode with a different secondary vertex identifier.
0192   /// @param id Secondary vertex identifier to set
0193   /// @return New barcode with modified secondary vertex identifier
0194   [[nodiscard]]
0195   constexpr Barcode withVertexSecondary(SecondaryVertexId id) const {
0196     Barcode barcode = *this;
0197     barcode.vertexSecondaryID = id;
0198     return barcode;
0199   }
0200 
0201   /// Create a new barcode with a different particle identifier.
0202   /// @param id Particle identifier to set
0203   /// @return New barcode with modified particle identifier
0204   [[nodiscard]]
0205   constexpr Barcode withParticle(ParticleId id) const {
0206     Barcode barcode = *this;
0207     barcode.particleID = id;
0208     return barcode;
0209   }
0210 
0211   /// Create a new barcode with a different generation identifier.
0212   /// @param id Generation identifier to set
0213   /// @return New barcode with modified generation identifier
0214   [[nodiscard]]
0215   constexpr Barcode withGeneration(GenerationId id) const {
0216     Barcode barcode = *this;
0217     barcode.generationID = id;
0218     return barcode;
0219   }
0220 
0221   /// Create a new barcode with a different sub-particle identifier.
0222   /// @param id Sub-particle identifier to set
0223   /// @return New barcode with modified sub-particle identifier
0224   [[nodiscard]]
0225   constexpr Barcode withSubParticle(SubParticleId id) const {
0226     Barcode barcode = *this;
0227     barcode.subParticleID = id;
0228     return barcode;
0229   }
0230 
0231   /// Create a new barcode from a vector
0232   /// @param data Vector containing exactly 5 elements
0233   /// @return New barcode with data from the vector
0234   [[nodiscard]]
0235   constexpr Barcode withData(std::span<std::uint32_t> data) {
0236     if (data.size() != 5) {
0237       throw std::invalid_argument(
0238           "Size of the data is " + std::to_string(data.size()) +
0239           " but Barcode requires data vector to have exactly 5 elements");
0240     }
0241 
0242     Barcode barcode = *this;
0243     barcode.vertexPrimaryID = data[0];
0244     barcode.vertexSecondaryID = data[1];
0245     barcode.particleID = data[2];
0246     barcode.generationID = data[3];
0247     barcode.subParticleID = data[4];
0248     return barcode;
0249   }
0250 
0251   /// Construct a new barcode representing a descendant particle.
0252   ///
0253   /// @param sub sub-particle index of the new barcode.
0254   /// @return New barcode with increased generation and specified sub-particle index
0255   Barcode makeDescendant(SubParticleId sub = 0u) const {
0256     Barcode barcode = *this;
0257     barcode.generationID += 1;
0258     barcode.subParticleID = sub;
0259     return barcode;
0260   }
0261 
0262   /// Reduce the barcode to the vertex identifier.
0263   /// @return Barcode containing only vertex and generation information
0264   constexpr Barcode vertexId() const {
0265     // The vertex is identified by primary vertex, secondary vertex, and
0266     // generation. The other components are set to 0 so two particle originating
0267     // from the same vertex will have the same vertex ID.
0268     Barcode barcode = *this;
0269     barcode.particleID = 0u;
0270     barcode.subParticleID = 0u;
0271     return barcode;
0272   }
0273 
0274   /// Reduce the barcode to the particle identifier.
0275   /// @return Barcode with subparticle identifier set to zero
0276   constexpr Barcode withoutSubparticle() const {
0277     // Provide a pseudo-barcode that contains all fields but not the
0278     // subparticle counter. This can be used as key in a map to store the
0279     // subparticle information
0280     Barcode barcode = *this;
0281     barcode.subParticleID = 0u;
0282     return barcode;
0283   }
0284 
0285   /// Print the barcode
0286   friend inline std::ostream& operator<<(std::ostream& os, Barcode barcode) {
0287     // extra "+" to ensure printing as a number and not as a character
0288     os << "vp=" << +barcode.vertexPrimary()
0289        << "|vs=" << +barcode.vertexSecondary() << "|p=" << +barcode.particle()
0290        << "|g=" << +barcode.generation() << "|sp=" << +barcode.subParticle();
0291     return os;
0292   }
0293 
0294   /// Get hash of the barcode
0295   /// @return Hash value of the barcode
0296   std::size_t hash() const {
0297     return Acts::hashMixAndCombine(vertexPrimary(), vertexSecondary(),
0298                                    particle(), generation(), subParticle());
0299   }
0300 
0301  private:
0302   PrimaryVertexId vertexPrimaryID = 0u;
0303   SecondaryVertexId vertexSecondaryID = 0u;
0304   ParticleId particleID = 0u;
0305   GenerationId generationID = 0u;
0306   SubParticleId subParticleID = 0u;
0307 };
0308 
0309 }  // namespace ActsFatras
0310 
0311 // specialize std::hash so Barcode can be used e.g. in an unordered_map
0312 namespace std {
0313 template <>
0314 struct hash<ActsFatras::Barcode> {
0315   auto operator()(ActsFatras::Barcode barcode) const noexcept {
0316     return barcode.hash();
0317   }
0318 };
0319 }  // namespace std