Templates

Template classes that define the core interfaces for AnalysisG components.

Overview

The templates module provides abstract base classes that users extend to create custom:

Event definitions
Particle types
Graph structures
Machine learning models
Performance metrics
Selection algorithms

These templates ensure consistency across the framework and enable polymorphic behavior.

Template Hierarchy

Event Template System

The event_template is the central abstraction for physics events. It provides:

Property system for event attributes
Tree/branch/leaf mapping for ROOT I/O
Abstract methods for building and compiling events
Integration with the analysis framework

Key methods: - clone(): Create event copies - build(element_t* el): Populate from ROOT - CompileEvent(): Finalize after building

Particle Template System

The particle_template represents individual physics objects (jets, leptons, etc.). Features:

4-momentum representation
Parent-child relationships for decay chains
Truth matching capabilities
Customizable properties

Attributes: - pt, eta, phi, e: Kinematics - Parents, Children: Decay chain - index: Unique identifier

Graph Template System

For graph neural network applications, the graph_template defines:

Node features from particles
Edge features from particle pairs
Global graph features from events
Automatic feature tensor construction

Methods: - NodeFeature(): Extract node features - EdgeFeature(): Compute edge features - GraphFeature(): Extract graph-level features

Model Template System

The model_template standardizes machine learning models:

Training/validation/test loops
Optimizer configuration
Loss function specification
Metric tracking
Checkpointing

Workflow: 1. Define model architecture 2. Specify loss and metrics 3. Configure optimizer 4. Train with automatic logging

Selection Template System

For cut-based analyses, the selection_template provides:

Event selection logic
Histogram booking
Cutflow tracking
Result serialization

Methods: - Selection(): Define cuts - InitHistograms(): Book histograms - ApplySelection(): Process events - Finalize(): Generate output

Metric Template System

Custom performance metrics via the metric_template:

Accumulation across batches
Reduction strategies
Metric computation
Logging integration

Interface: - Accumulate(): Update with batch - Compute(): Calculate final value - Reset(): Clear for new epoch

Design Philosophy

The template system follows several key principles:

Polymorphism: All templates use virtual methods for extensibility
Composition: Templates can be combined and nested
Type Safety: Cython provides compile-time type checking
Minimal Overhead: Templates add minimal runtime cost
Flexibility: Users can override any behavior

Template Usage Pattern

The typical workflow for using templates:

Inherit: Create a class inheriting from the appropriate template
Implement: Override abstract/virtual methods with custom logic
Register: Register your class with the analysis framework
Execute: The framework calls your implementations polymorphically

This pattern enables:

Code reuse across analyses
Standardized interfaces
Easy testing and validation
Interoperability between components

Interrelationships

Templates work together to form complete workflows:

Events contain Particles
Graphs are built from Events and Particles
Models train on Graphs using Metrics
Selections filter Events and create histograms
Analysis orchestrates all components

This modular design allows mixing and matching components for different analyses.

API Reference

The complete API documentation for template classes is automatically generated from source code using Doxygen and displayed below.

EventTemplate Class

class event_template : public tools

Subclassed by bsm_4tops, exp_mc20, gnn_event, ssml_mc20

Public Functions

event_template()

virtual ~event_template()

void add_leaf(std::string key, std::string leaf = "")

virtual event_template *clone()

virtual void build(element_t *el)

virtual void CompileEvent()

std::vector<particle_template*> double_neutrino(std::vector<particle_template*> *targets, double phi, double met, double limit = 1e3)

std::map<std::string, event_template*> build_event(std::map<std::string, data_t*> *evnt)

template<typename G> inline void register_particle(std::map<std::string, G*> *object)

template<typename G> inline void deregister_particle(std::map<std::string, G*> *object)

bool operator==(event_template &p)

void flush_particles()

Public Members

cproperty<std::vector<std::string>, event_template> trees

cproperty<std::vector<std::string>, event_template> branches

cproperty<std::vector<std::string>, event_template> leaves

cproperty<std::string, event_template> name

cproperty<std::string, event_template> hash

cproperty<std::string, event_template> tree

cproperty<double, event_template> weight

cproperty<long, event_template> index

std::map<std::string, std::string> m_trees

std::map<std::string, std::string> m_branches

std::map<std::string, std::string> m_leaves

event_t data

meta *meta_data = nullptr

std::string filename = ""

Public Static Functions

static void set_trees(std::vector<std::string>*, event_template*)

static void set_branches(std::vector<std::string>*, event_template*)

static void get_leaves(std::vector<std::string>*, event_template*)

static void set_name(std::string*, event_template*)

static void set_hash(std::string*, event_template*)

static void get_hash(std::string*, event_template*)

static void set_tree(std::string*, event_template*)

static void get_tree(std::string*, event_template*)

static void set_weight(double*, event_template*)

static void set_index(long*, event_template*)

ParticleTemplate Class

class particle_template : public tools

Subclassed by child, electron, electron, electron, jet, jet, jet, jetparton, lepton, muon, muon, muon, neutrino, particle_gnn, parton, physics_detector, physics_truth, top, top, top, top, top_children, truthjet, truthjet, truthjetparton, zboson, zprime

Public Functions

particle_template()

virtual ~particle_template()

explicit particle_template(particle_t *p)

explicit particle_template(particle_template *p, bool dump = false)

explicit particle_template(double px, double py, double pz, double e)

explicit particle_template(double px, double py, double pz)

void to_cartesian()

void to_polar()

bool is(std::vector<int> p)

double DeltaR(particle_template *p)

bool operator==(particle_template &p)

template<typename g> inline g operator+(g &p)

void operator+=(particle_template *p)

void iadd(particle_template *p)

bool register_parent(particle_template *p)

bool register_child(particle_template *p)

void add_leaf(std::string key, std::string leaf = "")

void apply_type_prefix()

std::map<std::string, std::map<std::string, particle_t>> __reduce__()

virtual void build(std::map<std::string, particle_template*> *event, element_t *el)

virtual particle_template *clone()

Public Members

cproperty<double, particle_template> e

cproperty<double, particle_template> pt

cproperty<double, particle_template> eta

cproperty<double, particle_template> phi

cproperty<double, particle_template> px

cproperty<double, particle_template> py

cproperty<double, particle_template> pz

cproperty<double, particle_template> mass

cproperty<double, particle_template> P

cproperty<double, particle_template> beta

cproperty<int, particle_template> pdgid

cproperty<std::string, particle_template> symbol

cproperty<double, particle_template> charge

cproperty<std::string, particle_template> hash

cproperty<bool, particle_template> is_b

cproperty<bool, particle_template> is_lep

cproperty<bool, particle_template> is_nu

cproperty<bool, particle_template> is_add

cproperty<bool, particle_template> lep_decay

cproperty<std::map<std::string, particle_template*>, particle_template> parents

cproperty<std::map<std::string, particle_template*>, particle_template> children

cproperty<std::string, particle_template> type

cproperty<int, particle_template> index

std::map<std::string, particle_template*> m_parents

std::map<std::string, particle_template*> m_children

std::map<std::string, std::string> leaves = {}

particle_t data

bool _is_serial = false

bool _is_marked = false

Public Static Functions

static void set_e(double*, particle_template*)

static void get_e(double*, particle_template*)

static void set_pt(double*, particle_template*)

static void get_pt(double*, particle_template*)

static void set_eta(double*, particle_template*)

static void get_eta(double*, particle_template*)

static void set_phi(double*, particle_template*)

static void get_phi(double*, particle_template*)

static void set_px(double*, particle_template*)

static void get_px(double*, particle_template*)

static void set_py(double*, particle_template*)

static void get_py(double*, particle_template*)

static void set_pz(double*, particle_template*)

static void get_pz(double*, particle_template*)

static void set_mass(double*, particle_template*)

static void get_mass(double*, particle_template*)

static void get_P(double*, particle_template*)

static void get_beta(double*, particle_template*)

static void set_pdgid(int*, particle_template*)

static void get_pdgid(int*, particle_template*)

static void set_symbol(std::string*, particle_template*)

static void get_symbol(std::string*, particle_template*)

static void set_charge(double*, particle_template*)

static void get_charge(double*, particle_template*)

static void get_hash(std::string*, particle_template*)

static void get_isb(bool*, particle_template*)

static void get_islep(bool*, particle_template*)

static void get_isnu(bool*, particle_template*)

static void get_isadd(bool*, particle_template*)

static void get_lepdecay(bool*, particle_template*)

static void set_parents(std::map<std::string, particle_template*>*, particle_template*)

static void get_parents(std::map<std::string, particle_template*>*, particle_template*)

static void set_children(std::map<std::string, particle_template*>*, particle_template*)

static void get_children(std::map<std::string, particle_template*>*, particle_template*)

static void set_type(std::string*, particle_template*)

static void get_type(std::string*, particle_template*)

static void set_index(int*, particle_template*)

static void get_index(int*, particle_template*)

GraphTemplate Class

class graph_template : public tools

Subclassed by graph_children, graph_detector, graph_detector, graph_detector, graph_jets, graph_jets, graph_jets, graph_jets_detector_lep, graph_jets_detector_lep, graph_jets_detector_lep, graph_jets_nonu, graph_jets_nonu, graph_jets_nonu, graph_tops, graph_truthjets, graph_truthjets_nonu

Public Functions

graph_template()

virtual ~graph_template()

virtual graph_template *clone()

virtual void CompileEvent()

virtual bool PreSelection()

void define_particle_nodes(std::vector<particle_template*> *prt)

void define_topology(std::function<bool(particle_template*, particle_template*)> fx)

void flush_particles()

bool operator==(graph_template &p)

template<typename G> inline G *get_event()

template<typename G, typename O, typename X> inline void add_graph_truth_feature(O *ev, X fx, std::string _name)

template<typename G, typename O, typename X> inline void add_graph_data_feature(O *ev, X fx, std::string _name)

template<typename G, typename O, typename X> inline void add_node_truth_feature(X fx, std::string _name)

template<typename G, typename O, typename X> inline void add_node_data_feature(X fx, std::string _name)

template<typename G, typename O, typename X> inline void add_edge_truth_feature(X fx, std::string _name)

template<typename G, typename O, typename X> inline void add_edge_data_feature(X fx, std::string _name)

Public Members

cproperty<long, graph_template> index

cproperty<double, graph_template> weight

cproperty<bool, graph_template> preselection

cproperty<std::string, graph_template> hash

cproperty<std::string, graph_template> tree

cproperty<std::string, graph_template> name

int threadIdx = -1

std::string filename = ""

meta *meta_data = nullptr

ModelTemplate Class

class model_template : public notification, public tools

Subclassed by grift, recursivegraphneuralnetwork

Public Functions

model_template()

virtual ~model_template()

virtual model_template *clone()

virtual void forward(graph_t *data)

virtual void train_sequence(bool mode)

void check_features(graph_t*)

void set_optimizer(std::string name)

void initialize(optimizer_params_t*)

void clone_settings(model_settings_t *setd)

void import_settings(model_settings_t *setd)

void forward(graph_t *data, bool train)

void forward(std::vector<graph_t*> data, bool train)

void register_module(torch::nn::Sequential *data)

void register_module(torch::nn::Sequential *data, mlp_init weight_init)

void prediction_graph_feature(std::string, torch::Tensor)

void prediction_node_feature(std::string, torch::Tensor)

void prediction_edge_feature(std::string, torch::Tensor)

void prediction_extra(std::string, torch::Tensor)

torch::Tensor *compute_loss(std::string, graph_enum)

void evaluation_mode(bool mode = true)

void save_state()

bool restore_state()

Public Members

cproperty<int, model_template> device_index

cproperty<std::string, model_template> name

cproperty<std::string, model_template> device

int kfold

int epoch

bool is_mc = false

bool use_pkl = false

bool inference_mode = false

bool enable_anomaly = false

bool retain_graph = false

std::string model_checkpoint_path = ""

std::string weight_name = "event_weight"

std::string tree_name = "nominal"

std::vector<torch::Tensor*> _losses = {}

torch::optim::Optimizer *m_optim = nullptr

cproperty<std::map<std::string, std::string>, std::map<std::string, std::tuple<torch::Tensor*, lossfx*>>> o_graph

cproperty<std::map<std::string, std::string>, std::map<std::string, std::tuple<torch::Tensor*, lossfx*>>> o_node

cproperty<std::map<std::string, std::string>, std::map<std::string, std::tuple<torch::Tensor*, lossfx*>>> o_edge

cproperty<std::vector<std::string>, std::map<std::string, torch::Tensor*>> i_graph

cproperty<std::vector<std::string>, std::map<std::string, torch::Tensor*>> i_node

cproperty<std::vector<std::string>, std::map<std::string, torch::Tensor*>> i_edge

Friends

friend struct graph_t

friend struct model_report

friend class metrics

friend class analysis

friend class optimizer

friend class dataloader

friend class metric_template

SelectionTemplate Class

class selection_template : public tools

Subclassed by childrenkinematics, combinatorial, decaymodes, matching, met, met, parton, regions, topefficiency, topjets, topkinematics, topkinematics, topmatching, topmatching, toptruthjets, validation, zprime, zprime

Public Functions

selection_template()

virtual ~selection_template()

virtual selection_template *clone()

virtual bool selection(event_template *ev)

virtual bool strategy(event_template *ev)

virtual void merge(selection_template *sel)

virtual void bulk_write(const long *idx, std::string *hx)

virtual void write(std::vector<particle_template*> *particles, std::string _name, particle_enum attrs)

template<typename g> inline void write(std::vector<g*> *particles, std::string _name, particle_enum attrs)

void switch_board(particle_enum attrs, particle_template *ptr, std::vector<std::vector<double>> *data)

void switch_board(particle_enum attrs, particle_template *ptr, std::vector<int> *data)

void switch_board(particle_enum attrs, particle_template *ptr, std::vector<double> *data)

void switch_board(particle_enum attrs, particle_template *ptr, std::vector<bool> *data)

template<typename g> inline void write(g *var, std::string _name)

template<typename g> inline void write(g var, std::string _name)

std::vector<std::map<std::string, float>> reverse_hash(std::vector<std::string> *hashes)

bool CompileEvent()

selection_template *build(event_template *ev)

bool operator==(selection_template &p)

template<typename g, typename k>
inline void sum(std::vector<g*> *ch, k **out)

template<typename g> inline void safe_delete(std::vector<g*> *particles)

template<typename g> inline g *sum(std::map<std::string, g*> *ch)

template<typename g> inline float sum(std::vector<g*> *ch)

template<typename g> inline std::vector<g*> vectorize(std::map<std::string, g*> *in)

template<typename g> inline std::vector<g*> make_unique(std::vector<g*> *inpt)

template<typename g> inline void downcast(std::vector<g*> *inpt, std::vector<particle_template*> *out)

template<typename o, typename g> inline void upcast(std::map<std::string, o*> *inpt, std::vector<g*> *out)

template<typename o, typename g> inline void upcast(std::vector<o*> *inpt, std::vector<g*> *out)

template<typename g> inline void get_leptonics(std::map<std::string, g*> inpt, std::vector<particle_template*> *out)

template<typename g, typename j> inline bool contains(std::vector<g*> *inpt, j *pcheck)

Public Members

cproperty<std::string, selection_template> name

cproperty<std::string, selection_template> hash

cproperty<std::string, selection_template> tree

cproperty<double, selection_template> weight

cproperty<long, selection_template> index

meta *meta_data = nullptr

std::string filename = ""

event_t data

int threadIdx = -1

std::map<std::string, std::map<std::string, float>> passed_weights = {}

std::map<std::string, meta_t> matched_meta = {}

Public Static Functions

static void set_name(std::string*, selection_template*)

static void get_name(std::string*, selection_template*)

static void set_hash(std::string*, selection_template*)

static void get_hash(std::string*, selection_template*)

static void get_tree(std::string*, selection_template*)

static void set_weight(double*, selection_template*)

static void get_weight(double*, selection_template*)

static void set_index(long*, selection_template*)

MetricTemplate Class

class metric_template : public tools, public notification

Subclassed by accuracy_metric, pagerank_metric

Public Functions

metric_template()

virtual ~metric_template()

virtual metric_template *clone()

virtual void define_variables()

virtual void define_metric(metric_t *v)

virtual void event()

virtual void batch()

virtual void end()

template<typename T> inline void register_output(std::string tree, std::string __name, T *t)

template<typename T> inline void write(std::string tree, std::string __name, T *t, bool fill = false)

template<typename g, typename k>
inline void sum(std::vector<g*> *ch, k **out)

template<typename g> inline void safe_delete(std::vector<g*> *particles)

template<typename g> inline std::vector<g*> make_unique(std::vector<g*> *inpt)

template<typename g> inline std::vector<g*> vectorize(std::map<std::string, g*> *in)

std::vector<particle_template*> make_particle(std::vector<std::vector<double>> *pt, std::vector<std::vector<double>> *eta, std::vector<std::vector<double>> *phi, std::vector<std::vector<double>> *energy)

Public Members

cproperty<std::string, metric_template> name

cproperty<std::string, metric_template> output_path

cproperty<std::vector<std::string>, metric_template> variables

cproperty<std::map<std::string, std::string>, metric_template> run_names