Particle Interface

The Particle Interface provides the foundation for defining custom particle types in AnalysisG.

Overview

Particles are the fundamental building blocks of events in HEP analyses. The ParticleTemplate class provides:

Four-momentum representation and manipulation
Particle identification (leptons, jets, etc.)
Parent-child relationships (decay chains)
Angular separation calculations
Four-momentum arithmetic operations

Core ParticleTemplate Class

File Location

Cython Implementation: src/AnalysisG/core/particle_template.pyx
Cython Header: src/AnalysisG/core/particle_template.pxd

Class Definition

class ParticleTemplate: The base class for all particle types in AnalysisG.

Properties

Four-Momentum Components

property px

Momentum x-component in GeV.

Type:: float

property py

Momentum y-component in GeV.

Type:: float

property pz

Momentum z-component in GeV.

Type:: float

property e

Energy in GeV.

Type:: float

Kinematic Properties

property pt

Transverse momentum in GeV.

Type:: float

property eta

Pseudorapidity.

Type:: float

property phi

Azimuthal angle in radians.

Type:: float

property mass

Invariant mass in GeV.

Type:: float

Particle Identification

property pdgid

PDG particle identification code.

Type:: int

property charge

Electric charge in units of elementary charge.

Type:: float

Decay Chain

property Parents

List of parent particles in the decay chain.

Type:: list[ParticleTemplate]

property Children

List of child particles in the decay chain.

Type:: list[ParticleTemplate]

Methods to Override

Particle Type Identification

is_lepton() → bool

Determine if particle is a lepton (e, μ, τ).

Returns:: True if particle is a lepton
Return type:: bool

is_jet() → bool

Determine if particle is a jet.

Returns:: True if particle is a jet
Return type:: bool

is_bjet() → bool

Determine if particle is a b-tagged jet.

Returns:: True if particle is a b-jet
Return type:: bool

Utility Methods

DeltaR(ParticleTemplate other) → float

Calculate angular separation (ΔR) from another particle.

Parameters:: other (ParticleTemplate) – Other particle
Returns:: Angular separation ΔR = √(Δη² + Δφ²)
Return type:: float

clone() → ParticleTemplate

Create a deep copy of this particle.

Returns:: Cloned particle
Return type:: ParticleTemplate

Operator Overloads

Four-Momentum Addition

__add__(ParticleTemplate other) → ParticleTemplate

Add four-momenta of two particles.

Parameters:: other (ParticleTemplate) – Particle to add
Returns:: New particle with combined four-momentum
Return type:: ParticleTemplate

__iadd__(ParticleTemplate other) → ParticleTemplate

In-place four-momentum addition.

Parameters:: other (ParticleTemplate) – Particle to add
Returns:: Self with updated four-momentum
Return type:: ParticleTemplate

Usage Examples

Basic Particle Selection

from AnalysisG.core import ParticleTemplate

class MyParticle(ParticleTemplate):
    def is_lepton(self):
        # Electrons and muons
        return abs(self.pdgid) in [11, 13]

    def is_jet(self):
        # Jets typically have pdgid of 0 or large values
        return self.pdgid == 0

Custom Particle Type

from AnalysisG.core import ParticleTemplate

class Electron(ParticleTemplate):
    def __init__(self, data=None):
        super().__init__(data)
        self.isolation = 0.0

    def is_lepton(self):
        return True

    def is_isolated(self):
        return self.isolation < 0.1

Four-Momentum Operations

# Combine particles
top_candidate = lepton + jet1 + jet2

# Check invariant mass
if 150 < top_candidate.mass < 200:
    print(f"Top candidate found: m = {top_candidate.mass:.1f} GeV")

# Calculate separation
dr = lepton.DeltaR(jet1)
if dr > 0.4:
    print("Particles are well separated")

Best Practices

Preserve immutability: Use + operator for new particles, += for in-place modification.
Check PDG IDs carefully: Different experiments may use different conventions.
Handle missing data: Check for None or invalid values before calculations.
Use DeltaR for isolation: Common pattern for checking particle isolation.