Warning, /acts/docs/groups/fatras.md is written in an unsupported language. File is not indexed.
0001 @defgroup fatras Fatras
0002 @brief Fast track simulation on ACTS tracking geometries.
0003
0004 # Fatras
0005
0006 Fatras is the ACTS fast track simulation package. It uses the
0007 @ref Acts::Propagator and a reconstruction-oriented @ref Acts::TrackingGeometry
0008 to transport particles through the detector and to produce simulated hits on
0009 sensitive surfaces. It is intended for fast algorithm validation and detector
0010 studies that do not require a full, detailed detector simulation.
0011
0012 Fatras uses parametrized material interactions, including multiple scattering,
0013 Bethe-Bloch energy loss, Bethe-Heitler energy loss, and photon conversion. Since
0014 it operates on tracking surfaces rather than a full volumetric detector model,
0015 it is faster than a detailed Geant4 simulation but also less complete.
0016
0017 ## Barcode identifiers {#fatras_barcode_identifiers}
0018
0019 Fatras labels simulated particles and hits with @ref ActsFatras::Barcode. A
0020 barcode is the event-local particle identifier used by Fatras and by the ACTS
0021 examples framework for truth matching. It is not a geometry identifier; it
0022 answers "which simulated particle produced this object?".
0023
0024 The barcode stores five integer components:
0025
0026 | Component | Meaning |
0027 | --------- | ------- |
0028 | primary vertex | The primary interaction vertex. Ordinary simulated particles use a non-zero primary vertex. |
0029 | secondary vertex | A secondary vertex below the primary vertex. Zero means the particle comes directly from the primary vertex. |
0030 | particle | The particle number within the selected primary and secondary vertex. |
0031 | generation | The descendant generation. Particles produced at the vertex use generation zero. |
0032 | sub-particle | The particle number within a non-zero generation. Particles produced at the vertex use sub-particle zero. |
0033
0034 The default-constructed barcode has all components set to zero and represents an
0035 invalid, missing, or unknown particle identifier. This value is useful as a
0036 sentinel, but it should not be used for ordinary simulated particles.
0037
0038 For example, a particle from primary vertex `2` with particle number `14` is
0039 encoded as:
0040
0041 ```text
0042 vp=2|vs=0|p=14|g=0|sp=0
0043 ```
0044
0045 If a Fatras interaction creates two descendant particles from this particle, the
0046 new particles keep the same vertex and particle number. The generation is
0047 increased and the sub-particle number distinguishes the two descendants:
0048
0049 ```text
0050 vp=2|vs=0|p=14|g=1|sp=0
0051 vp=2|vs=0|p=14|g=1|sp=1
0052 ```
0053
0054 The preserved vertex and particle components make it cheap to recover the
0055 initial simulated particle for truth matching, while the generation and
0056 sub-particle components distinguish particles created during the simulation.
0057
0058 ## Creating and reducing barcodes
0059
0060 @ref ActsFatras::Barcode is immutable from the caller's point of view: modifier
0061 methods return a new barcode with one component changed. Typical construction
0062 therefore chains the `with...` methods:
0063
0064 ```cpp
0065 auto particleId = ActsFatras::Barcode()
0066 .withVertexPrimary(1)
0067 .withVertexSecondary(0)
0068 .withParticle(42);
0069 ```
0070
0071 Interactions that create descendants can call
0072 @ref ActsFatras::Barcode::makeDescendant to increase the generation and set the
0073 sub-particle number:
0074
0075 ```cpp
0076 auto electronId = photonId.makeDescendant(0);
0077 auto positronId = photonId.makeDescendant(1);
0078 ```
0079
0080 Two helper projections are commonly useful when grouping truth information:
0081
0082 - @ref ActsFatras::Barcode::vertexId drops the particle and sub-particle
0083 components so objects can be grouped by production vertex.
0084 - @ref ActsFatras::Barcode::withoutSubparticle drops only the sub-particle
0085 component so generated descendants can be grouped by original particle and
0086 generation.
0087
0088 Since barcodes are created locally by the code that produces particles, there is
0089 no global allocation service that stores the full decay tree. Independent
0090 interactions can therefore create overlapping descendant identifiers if they
0091 start from the same particle and generation. When the full set of particles is
0092 available, sub-particle numbers within a generation can be renumbered to make
0093 the identifiers unique.
