EIC code displayed by LXR master/​include/​ActsFatras/​EventData/​Barcode.hpp	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

File indexing completed on 2025-12-16 09:41:49

 // This file is part of the ACTS project.
 //
 // Copyright (C) 2016 CERN for the benefit of the ACTS project
 //
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 
 #pragma once
 
 #include <cstdint>
 #include <span>
 #include <stdexcept>
 #include <string>
 #include <vector>
 
 #include <boost/functional/hash.hpp>
 
 namespace ActsFatras {
 
 /// Particle identifier that encodes additional event information.
 ///
 /// The barcode has to fulfill two separate requirements: be able to act as
 /// unique identifier for particles within an event and to encode details
 /// on the event structure for fast lookup. Since we only care about tracking
 /// here, we need to support two scenarios:
 ///
 /// *   Identify which primary/secondary vertex particles belong to. No
 ///     information on intermediate/unstable/invisible particles needs to be
 ///     retained. This information is already available in the underlying
 ///     generator event and should not be duplicated.
 /// *   If (visible) particles convert, decay, or interact with the detector,
 ///     we need to be able to identify the initial (primary) particle. Typical
 ///     examples are pion nuclear interactions or electron/gamma conversions.
 ///
 /// The vertex information is encoded as two numbers that define the
 /// primary and secondary vertex. The primary vertex must be non-zero.
 /// Particles with a zero secondary vertex originate directly from the primary
 /// vertex.
 ///
 /// Within one vertex (primary+secondary) each particle is identified by
 /// a particle, generation, and sub-particle number. Particles originating
 /// from the vertex must have zero generation and zero sub-particle number;
 /// a consequence is that only non-zero generation can have non-zero
 /// sub-particle numbers. A non-zero generation indicates that the particle
 /// is a descendant of the original particle, e.g. from interactions or decay,
 /// while the sub-particle number identifies the descendant particle.
 ///
 /// With this encoding, non-primary particles and their primary parent can
 /// be easily identified at the expense of not storing the exact decay history.
 ///
 /// A barcode with all elements set to zero (the default value) is an invalid
 /// value that can be used e.g. to mark missing or unknown particles.
 ///
 /// ## Example
 ///
 /// A particle generated in a primary interaction might have the barcode
 ///
 ///     2|0|14|0|0 -> vertex=2 (primary), particle=14, generation=0, sub=0
 ///
 /// A simulation module might generate an interaction and create two new
 /// particles. These are descendants of the initial particle and the simulation
 /// module can generate the new barcodes directly by increasing the
 /// generation number and choosing sub-particle identifiers:
 ///
 ///     2|0|14|1|0 -> vertex=2 (primary), particle=14, generation=1, sub=0
 ///     2|0|14|1|1 -> vertex=2 (primary), particle=14, generation=1, sub=1
 ///
 /// If these secondary particles generate further tertiary particles
 /// the barcode would be e.g.
 ///
 ///     2|0|14|2|0 -> vertex=2 (primary), particle=14, generation=2, sub=0
 ///
 /// ## Possible issues
 ///
 /// The hierarchical nature of the barcode allows barcode creation without
 /// a central service. Since the full history is not stored, generated barcodes
 /// for higher-generation particles can overlap when generated by independent
 /// interactions. Assuming an initial primary particle with barcode
 ///
 ///     3|4|5|0|0 -> particle=5
 ///
 /// a first interaction might create a secondary particle by increasing the
 /// generation number (without destroying the initial particle)
 ///
 ///     3|4|5|1|0 -> particle=5, generation+=1, first sub-particle
 ///
 /// The initial particle gets simulated further and at another step a second
 /// interaction also creates a new particle. Since it knows nothing about
 /// the previously created particle (no central service), it will generate
 ///
 ///     3|4|5|1|0 -> particle=5, generation+=1, first sub-particle
 ///
 /// which is identical to the previously create barcode. These cases can be
 /// easily solved by renumbering the sub-particle identifier within each
 /// generation to contain unique values. However, this can only be done when all
 /// particles are known.
 class Barcode {
  public:
   using PrimaryVertexId = std::uint16_t;
   using SecondaryVertexId = std::uint16_t;
   using ParticleId = std::uint32_t;
   using GenerationId = std::uint8_t;
   using SubParticleId = std::uint32_t;
 
   // Construct an invalid barcode with all levels set to zero.
   static constexpr Barcode Invalid() { return Barcode(); }
 
   /// Empty barcode
   constexpr Barcode() = default;
   /// Copy constructor
   constexpr Barcode(const Barcode&) = default;
   /// Move constructor
   constexpr Barcode(Barcode&&) = default;
   /// Copy assignment operator
   /// @return Reference to this barcode after copying
   Barcode& operator=(const Barcode&) = default;
   /// Move assignment operator
   /// @return Reference to this barcode after moving
   Barcode& operator=(Barcode&&) = default;
 
   ///  Compare two barcodes
   bool operator==(const Barcode&) const = default;
   friend constexpr auto operator<=>(Barcode lhs, Barcode rhs) {
     return lhs.asVector() <=> rhs.asVector();
   }
 
   /// Check validity of the barcode
   static constexpr bool isValid(const Barcode& b) { return b != Invalid(); }
   constexpr bool isValid() const { return isValid(*this); }
 
   /// Return the primary vertex identifier.
   /// @return The primary vertex identifier value
   constexpr PrimaryVertexId vertexPrimary() const { return vertexPrimaryID; }
 
   /// Return the secondary vertex identifier.
   /// @return The secondary vertex identifier value
   constexpr SecondaryVertexId vertexSecondary() const {
     return vertexSecondaryID;
   }
 
   /// Return the particle identifier.
   /// @return The particle identifier value
   constexpr ParticleId particle() const { return particleID; }
 
   /// Return the generation identifier.
   /// @return The generation identifier value
   constexpr GenerationId generation() const { return generationID; }
 
   /// Return the sub-particle identifier.
   /// @return The sub-particle identifier value
   constexpr SubParticleId subParticle() const { return subParticleID; }
 
   /// Export barcode as vector
   constexpr std::vector<std::uint32_t> asVector() const {
     return {vertexPrimary(), vertexSecondary(), particle(), generation(),
             subParticle()};
   }
 
   /// Set the primary vertex identifier.
   /// @param id Primary vertex identifier to set
   /// @return Reference to this barcode for chaining
   [[deprecated("Use withVertexPrimary() instead")]]
   constexpr Barcode& setVertexPrimary(PrimaryVertexId id) {
     vertexPrimaryID = id;
     return *this;
   }
 
   /// Set the secondary vertex identifier.
   /// @param id Secondary vertex identifier to set
   /// @return Reference to this barcode for chaining
   [[deprecated("Use withVertexSecondary() instead")]]
   constexpr Barcode& setVertexSecondary(SecondaryVertexId id) {
     vertexSecondaryID = id;
     return *this;
   }
 
   /// Set the parent particle identifier.
   /// @param id Particle identifier to set
   /// @return Reference to this barcode for chaining
   [[deprecated("Use withParticle() instead")]]
   constexpr Barcode& setParticle(ParticleId id) {
     particleID = id;
     return *this;
   }
 
   /// Set the particle identifier.
   /// @param id Generation identifier to set
   /// @return Reference to this barcode for chaining
   [[deprecated("Use withGeneration() instead")]]
   constexpr Barcode& setGeneration(GenerationId id) {
     generationID = id;
     return *this;
   }
 
   /// Set the process identifier.
   /// @param id Sub-particle identifier to set
   /// @return Reference to this barcode for chaining
   [[deprecated("Use withSubParticle() instead")]]
   constexpr Barcode& setSubParticle(SubParticleId id) {
     subParticleID = id;
     return *this;
   }
 
   /// Create a new barcode with a different primary vertex identifier.
   /// @param id Primary vertex identifier to set
   /// @return New barcode with modified primary vertex identifier
   [[nodiscard]]
   constexpr Barcode withVertexPrimary(PrimaryVertexId id) const {
     Barcode barcode = *this;
     barcode.vertexPrimaryID = id;
     return barcode;
   }
 
   /// Create a new barcode with a different secondary vertex identifier.
   /// @param id Secondary vertex identifier to set
   /// @return New barcode with modified secondary vertex identifier
   [[nodiscard]]
   constexpr Barcode withVertexSecondary(SecondaryVertexId id) const {
     Barcode barcode = *this;
     barcode.vertexSecondaryID = id;
     return barcode;
   }
 
   /// Create a new barcode with a different particle identifier.
   /// @param id Particle identifier to set
   /// @return New barcode with modified particle identifier
   [[nodiscard]]
   constexpr Barcode withParticle(ParticleId id) const {
     Barcode barcode = *this;
     barcode.particleID = id;
     return barcode;
   }
 
   /// Create a new barcode with a different generation identifier.
   /// @param id Generation identifier to set
   /// @return New barcode with modified generation identifier
   [[nodiscard]]
   constexpr Barcode withGeneration(GenerationId id) const {
     Barcode barcode = *this;
     barcode.generationID = id;
     return barcode;
   }
 
   /// Create a new barcode with a different sub-particle identifier.
   /// @param id Sub-particle identifier to set
   /// @return New barcode with modified sub-particle identifier
   [[nodiscard]]
   constexpr Barcode withSubParticle(SubParticleId id) const {
     Barcode barcode = *this;
     barcode.subParticleID = id;
     return barcode;
   }
 
   /// Create a new barcode from a vector
   /// @param data Vector containing exactly 5 elements
   /// @return New barcode with data from the vector
   [[nodiscard]]
   constexpr Barcode withData(std::span<std::uint32_t> data) {
     if (data.size() != 5) {
       throw std::invalid_argument(
           "Size of the data is " + std::to_string(data.size()) +
           " but Barcode requires data vector to have exactly 5 elements");
     }
 
     Barcode barcode = *this;
     barcode.vertexPrimaryID = data[0];
     barcode.vertexSecondaryID = data[1];
     barcode.particleID = data[2];
     barcode.generationID = data[3];
     barcode.subParticleID = data[4];
     return barcode;
   }
 
   /// Construct a new barcode representing a descendant particle.
   ///
   /// @param sub sub-particle index of the new barcode.
   /// @return New barcode with increased generation and specified sub-particle index
   Barcode makeDescendant(SubParticleId sub = 0u) const {
     Barcode barcode = *this;
     barcode.generationID += 1;
     barcode.subParticleID = sub;
     return barcode;
   }
 
   /// Reduce the barcode to the vertex identifier.
   /// @return Barcode containing only vertex and generation information
   constexpr Barcode vertexId() const {
     // The vertex is identified by primary vertex, secondary vertex, and
     // generation. The other components are set to 0 so two particle originating
     // from the same vertex will have the same vertex ID.
     Barcode barcode = *this;
     barcode.particleID = 0u;
     barcode.subParticleID = 0u;
     return barcode;
   }
 
   /// Reduce the barcode to the particle identifier.
   constexpr Barcode withoutSubparticle() const {
     // Provide a pseudo-barcode that contains all fields but not the
     // subparticle counter. This can be used as key in a map to store the
     // subparticle information
     Barcode barcode = *this;
     barcode.subParticleID = 0u;
     return barcode;
   }
 
   /// Print the barcode
   friend inline std::ostream& operator<<(std::ostream& os, Barcode barcode) {
     // extra "+" to ensure printing as a number and not as a character
     os << "vp=" << +barcode.vertexPrimary()
        << "|vs=" << +barcode.vertexSecondary() << "|p=" << +barcode.particle()
        << "|g=" << +barcode.generation() << "|sp=" << +barcode.subParticle();
     return os;
   }
 
   /// Get hash of the barcode
   std::size_t hash() const {
     std::size_t seed = 0;
     boost::hash_combine(seed, vertexPrimary());
     boost::hash_combine(seed, vertexSecondary());
     boost::hash_combine(seed, particle());
     boost::hash_combine(seed, generation());
     boost::hash_combine(seed, subParticle());
 
     return seed;
   }
 
  private:
   PrimaryVertexId vertexPrimaryID = 0u;
   SecondaryVertexId vertexSecondaryID = 0u;
   ParticleId particleID = 0u;
   GenerationId generationID = 0u;
   SubParticleId subParticleID = 0u;
 };
 
 }  // namespace ActsFatras
 
 // specialize std::hash so Barcode can be used e.g. in an unordered_map
 namespace std {
 template <>
 struct hash<ActsFatras::Barcode> {
   auto operator()(ActsFatras::Barcode barcode) const noexcept {
     return barcode.hash();
   }
 };
 }  // namespace std

This page was automatically generated by the 2.3.7 LXR engine. The LXR team