C++ Modules Complete Reference

This document provides comprehensive documentation for all 23 C++ modules in AnalysisG.

Location: src/AnalysisG/modules/*/

Module Overview

The modules are organized into categories:

  1. Core Templates: particle, event, graph, selection, metric, model, lossfx

  2. Data Management: io, container, dataloader, sampletracer

  3. Analysis: analysis, optimizer, metrics, plotting, roc

  4. Physics: nusol (neutrino reconstruction)

  5. Infrastructure: structs, tools, typecasting, notification, meta

Each module is a self-contained C++ library with headers in include/ and implementations in cxx/.

Core Template Modules

particle

Header: modules/particle/include/templates/particle_template.h

Four-momentum particle representation with kinematics and identification.

Key Class: particle_template

class particle_template : public tools {
public:
    // Constructors
    particle_template();
    particle_template(particle_t* p);
    particle_template(double px, double py, double pz, double e);
    particle_template(double px, double py, double pz);  // massless

    // Four-momentum properties (cproperty provides getters/setters)
    cproperty<double, particle_template> px, py, pz, e;
    cproperty<double, particle_template> pt, eta, phi, mass;
    cproperty<double, particle_template> P;     // momentum magnitude
    cproperty<double, particle_template> beta;  // velocity β = P/E

    // Identification
    cproperty<int, particle_template> pdgid;
    cproperty<double, particle_template> charge;
    cproperty<std::string, particle_template> symbol;  // "e-", "μ+", etc.
    cproperty<std::string, particle_template> type;    // "jet", "electron", etc.
    cproperty<std::string, particle_template> hash;    // unique identifier
    cproperty<int, particle_template> index;

    // Boolean type flags
    cproperty<bool, particle_template> is_b;         // b-quark/jet
    cproperty<bool, particle_template> is_lep;       // lepton
    cproperty<bool, particle_template> is_nu;        // neutrino
    cproperty<bool, particle_template> is_add;       // additional particle
    cproperty<bool, particle_template> lep_decay;    // from leptonic decay

    // Decay chain
    cproperty<std::map<std::string, particle_template*>, particle_template> parents;
    cproperty<std::map<std::string, particle_template*>, particle_template> children;

    // Methods
    double DeltaR(particle_template* p);  // Angular separation
    bool is(std::vector<int> pdgids);      // Check if PDG ID in list
    void to_cartesian();                    // Convert from polar
    void to_polar();                        // Convert to polar

    // Operators
    bool operator==(particle_template& p);
    template<typename g> g operator+(g& p);  // Four-momentum addition
    void operator+=(particle_template* p);
    void iadd(particle_template* p);

    // Serialization
    std::map<std::string, std::map<std::string, particle_t>> __reduce__();

    // Decay chain management
    bool register_parent(particle_template* p);
    bool register_child(particle_template* p);
    std::map<std::string, particle_template*> m_parents;
    std::map<std::string, particle_template*> m_children;

    // ROOT variable mapping
    void add_leaf(std::string key, std::string leaf = "");
    std::map<std::string, std::string> leaves;

    // Cloning and building
    virtual particle_template* clone();
    virtual void build(std::map<std::string, particle_template*>* event, element_t* el);

    particle_t data;  // Underlying data structure
};

Usage:

particle_template* electron = new particle_template();
electron->px = 25000.0;  // MeV
electron->py = 15000.0;
electron->pz = 40000.0;
electron->e  = 50000.0;

double pt_val = electron->pt;   // Computed: √(px²+py²)
double eta_val = electron->eta; // Computed: -ln(tan(θ/2))

electron->pdgid = 11;     // Electron PDG ID
electron->charge = -1.0;
electron->type = "electron";

// Check if it's a lepton
bool is_lepton = electron->is_lep;  // true for e, μ, τ

// Compute angular separation
double dr = electron->DeltaR(muon);

event

Header: modules/event/include/templates/event_template.h

Event-level container managing particles and metadata.

Key Class: event_template

class event_template : public tools {
public:
    event_template();
    virtual ~event_template();

    // ROOT tree configuration
    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> tree;

    // Event identification
    cproperty<std::string, event_template> name;
    cproperty<std::string, event_template> hash;
    cproperty<double, event_template> weight;
    cproperty<long, event_template> index;

    // Particle registration
    template<typename G>
    void register_particle(std::map<std::string, G*>* object);

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

    // Virtual methods for inheritance
    virtual event_template* clone();
    virtual void build(element_t* el);
    virtual void CompileEvent();

    // Event building
    std::map<std::string, event_template*> build_event(
        std::map<std::string, data_t*>* evnt
    );

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

    // Operators
    bool operator==(event_template& p);

    // Data members
    event_t data;
    meta* meta_data;
    std::string filename;

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

private:
    void build_mapping(std::map<std::string, data_t*>* evnt);
    void flush_leaf_string();

    std::map<std::string, bool> next_;
    std::map<std::string, particle_template*> particle_generators;
    std::map<std::string, std::map<std::string, element_t>> tree_variable_link;
    std::map<std::string, std::map<std::string, particle_template*>*> particle_link;
    std::map<std::string, particle_template*> garbage;
};

graph

Header: modules/graph/include/templates/graph_template.h

Graph representation for GNN processing.

Key Class: graph_template

class graph_template : public tools {
public:
    graph_template();
    virtual ~graph_template();

    // Graph structure
    cproperty<std::string, graph_template> name;
    cproperty<std::string, graph_template> hash;

    // Virtual methods
    virtual graph_template* clone();
    virtual void build(event_template* ev);

    // Graph data
    graph_t data;

    // Node and edge management
    void add_node(particle_template* p);
    void add_edge(int src, int dst, double weight = 1.0);

    // Adjacency operations
    void build_adjacency();
    std::vector<std::vector<int>> get_adjacency_list();

    bool operator==(graph_template& g);
};

selection

Header: modules/selection/include/templates/selection_template.h

Custom selection/filtering logic.

Key Class: selection_template

class selection_template : public tools {
public:
    selection_template();
    virtual ~selection_template();

    cproperty<std::string, selection_template> name;
    cproperty<std::string, selection_template> hash;

    virtual selection_template* clone();
    virtual void selection(event_template* ev);
    virtual void selection(graph_template* gr);

    selection_t data;
    bool operator==(selection_template& s);
};

metric

Header: modules/metric/include/templates/metric_template.h

Evaluation metrics for model performance.

Key Class: metric_template

class metric_template : public tools {
public:
    metric_template();
    virtual ~metric_template();

    cproperty<std::string, metric_template> name;

    virtual metric_template* clone();
    virtual void calculate(/* model outputs */);

    metric_t data;
};

model

Header: modules/model/include/templates/model_template.h

Machine learning model template.

Key Class: model_template

class model_template : public tools {
public:
    model_template();
    virtual ~model_template();

    cproperty<std::string, model_template> name;

    virtual model_template* clone();
    virtual void forward(/* inputs */);
    virtual void backward(/* gradients */);

    model_t data;

    // State management
    void save_state(std::string path);
    void load_state(std::string path);
};

lossfx

Header: modules/lossfx/include/templates/lossfx.h

Loss function definitions.

Key Class: lossfx

class lossfx : public tools {
public:
    lossfx();
    virtual ~lossfx();

    cproperty<std::string, lossfx> name;

    virtual double calculate(/* predictions, targets */);
    virtual void backward(/* gradients */);

    loss_t data;
};

Data Management Modules

io

Header: modules/io/include/io/io.h

Input/output operations for ROOT and HDF5 files.

Key Class: io

class io : public tools, public notification {
public:
    io();
    ~io();

    // HDF5 operations
    template<typename g>
    void write(std::vector<g>* inpt, std::string set_name);

    template<typename g>
    void write(g* inpt, std::string set_name);

    template<typename g>
    void read(std::vector<g>* outpt, std::string set_name);

    template<typename g>
    void read(g* out, std::string set_name);

    // File management
    bool start(std::string filename, std::string read_write);
    void end();
    std::vector<std::string> dataset_names();

    // ROOT operations
    std::map<std::string, long> root_size();
    void check_root_file_paths();
    bool scan_keys();
    void root_begin();
    void root_end();
    void trigger_pcm();
    void import_settings(settings_t* params);
    std::map<std::string, data_t*>* get_data();

    // Configuration
    bool enable_pyami;
    std::string metacache_path;
    std::string current_working_path;
    // ... (many more members)
};

Features:

  • Reads ROOT TTrees with branch/leaf access

  • Writes/reads HDF5 datasets

  • Automatic type detection

  • Metadata caching

  • Progress tracking

container

Header: modules/container/include/container/container.h

Container for managing event/graph/selection collections.

Key Class: container

class container : public tools {
public:
    container();
    ~container();

    // Metadata
    void add_meta_data(meta*, std::string);
    meta* get_meta_data();

    // Template management
    bool add_selection_template(selection_template*);
    bool add_event_template(event_template*, std::string label);
    bool add_graph_template(graph_template*, std::string label);

    // Population
    void fill_selections(std::map<std::string, selection_template*>* inpt);
    void get_events(std::vector<event_template*>*, std::string label);
    void populate_dataloader(dataloader* dl);

    // Processing
    void compile(size_t* len, int threadIdx);
    size_t len();
    entry_t* add_entry(std::string hash);

    // Data members
    meta* meta_data;
    std::string* filename;
    std::string* output_path;
    std::string label;
    std::map<std::string, entry_t> random_access;
    std::map<std::string, selection_template*>* merged;
};

Helper Struct: entry_t

struct entry_t {
    std::string hash;
    std::vector<graph_t*> m_data;
    std::vector<graph_template*> m_graph;
    std::vector<event_template*> m_event;
    std::vector<selection_template*> m_selection;

    void init();
    void destroy();
    bool has_event(event_template* ev);
    bool has_graph(graph_template* gr);
    bool has_selection(selection_template* sel);
};

dataloader

Header: modules/dataloader/include/generators/dataloader.h

Batch data loading for training.

Key Class: dataloader

class dataloader : public tools {
public:
    dataloader();
    ~dataloader();

    // Batch operations
    void add_batch(/* data */);
    void shuffle();
    void reset();

    // Configuration
    void set_batch_size(size_t size);
    void set_num_workers(int workers);

    // Iteration
    bool next_batch(/* output */);
    size_t num_batches();

    dataloader_t data;
};

sampletracer

Header: modules/sampletracer/include/generators/sampletracer.h

Tracks sample metadata (cross-sections, weights).

Key Class: sampletracer

class sampletracer : public tools {
public:
    sampletracer();
    ~sampletracer();

    // Sample tracking
    void add_sample(std::string label, double xsec, double weight);
    double get_cross_section(std::string label);
    double get_sum_of_weights(std::string label);

    // Normalization
    double get_scale_factor(std::string label, double lumi);

    sampletracer_t data;
};

Analysis Modules

analysis

Header: modules/analysis/include/AnalysisG/analysis.h

Main orchestrator coordinating all analysis components.

Key Class: analysis

class analysis : public notification, public tools {
public:
    analysis();
    ~analysis();

    // Configuration
    void add_samples(std::string path, std::string label);
    void add_selection_template(selection_template* sel);
    void add_event_template(event_template* ev, std::string label);
    void add_graph_template(graph_template* gr, std::string label);
    void add_metric_template(metric_template* mx, model_template* mdl);
    void add_model(model_template* model, optimizer_params_t* op,
                   std::string run_name);
    void add_model(model_template* model, std::string run_name);  // inference

    // Execution
    void start();
    void attach_threads();

    // Progress tracking
    std::map<std::string, std::vector<float>> progress();
    std::map<std::string, std::string> progress_mode();
    std::map<std::string, std::string> progress_report();
    std::map<std::string, bool> is_complete();

    // Configuration
    settings_t m_settings;
    std::map<std::string, meta*> meta_data;

private:
    void check_cache();
    void build_project();
    void build_events();
    void build_selections();
    void build_graphs();
    void build_model_session();
    void build_inference();
    bool build_metric();
    void build_metric_folds();
    void build_dataloader(bool training);
    void fetchtags();

    // Threading
    static void execution(/* params */);
    static void execution_metric(/* params */);
    static void initialize_loop(/* params */);

    // Internal state
    std::map<std::string, std::string> file_labels;
    std::map<std::string, event_template*> event_labels;
    std::map<std::string, metric_template*> metric_names;
    std::map<std::string, selection_template*> selection_names;
    std::map<std::string, std::map<std::string, graph_template*>> graph_labels;

    std::vector<std::string> model_session_names;
    std::map<std::string, model_template*> model_inference;
    std::map<std::string, model_template*> model_metrics;
    std::vector<std::tuple<model_template*, optimizer_params_t*>> model_sessions;

    std::map<std::string, optimizer*> trainer;
    std::map<std::string, model_report*> reports;
    std::vector<std::thread*> threads;

    std::vector<folds_t>* tags;
    dataloader* loader;
    sampletracer* tracer;
    io* reader;

    bool started;
};

optimizer

Header: modules/optimizer/include/generators/optimizer.h

Training optimization (Adam, SGD, etc.).

Key Class: optimizer

class optimizer : public tools {
public:
    optimizer();
    ~optimizer();

    // Configuration
    void set_learning_rate(double lr);
    void set_momentum(double momentum);
    void set_weight_decay(double decay);

    // Training
    void zero_grad();
    void step();

    // State
    void save_state(std::string path);
    void load_state(std::string path);

    optimizer_t data;
    optimizer_params_t params;
};

metrics

Header: modules/metrics/include/metrics/metrics.h

Metric computation utilities.

plotting

Header: modules/plotting/include/plotting/plotting.h

Plotting utilities for analysis results.

roc

Header: modules/roc/include/plotting/roc.h

ROC curve computation and plotting.

Physics Module

nusol

Location: modules/nusol/nusol/include/reconstruction/nusol.h

Neutrino momentum reconstruction algorithms.

Key Features:

  • Analytical W→lν solver

  • Numerical ttbar→lνblνb solver

  • Multiple solution handling

  • Constraint optimization

Infrastructure Modules

structs

Location: modules/structs/include/structs/

Core data structures used throughout.

Key Structures:

struct particle_t {
    double px, py, pz, e;
    int pdgid, index;
    double charge;
    std::string type;
    bool polar;
    // ... more fields
};

struct event_t {
    long index;
    double weight;
    std::string hash, name, tree;
    std::vector<std::string> trees, branches;
    // ... more fields
};

struct graph_t {
    std::vector<long> edge_index;
    std::vector<double> edge_attr;
    std::vector<double> node_attr;
    // ... more fields
};

struct settings_t {
    std::string output_path;
    std::string sow_name;
    int kfolds;
    std::vector<int> kfold;
    // ... more fields
};

tools

Header: modules/tools/include/tools/tools.h

Utility functions and base class.

Key Class: tools

class tools {
public:
    tools();
    virtual ~tools();

    // String operations
    std::string env(const std::string& s);
    std::string enc(const std::string& s);

    // Vector operations
    template<typename T>
    std::vector<T> flatten(std::vector<std::vector<T>> v);

    // Hashing
    std::string hash_string(const std::string& s);

    // Progress/logging (inherits notification)
    void success(std::string msg);
    void failure(std::string msg);
    void warning(std::string msg);
};

typecasting

Location: modules/typecasting/include/tools/

Type conversion utilities between Python/C++/ROOT.

Key Functions:

  • merge_cast.h: Merge different data types

  • vector_cast.h: Vector type conversions

notification

Header: modules/notification/include/notification/notification.h

Logging and progress notification system.

Key Class: notification

class notification {
public:
    notification();
    virtual ~notification();

    void success(std::string msg);
    void failure(std::string msg);
    void warning(std::string msg);
    void info(std::string msg);

    // Progress tracking
    void set_progress(double percent);
    double get_progress();

protected:
    std::string format_message(std::string level, std::string msg);
};

meta

Header: modules/meta/include/meta/meta.h

Metadata management for datasets.

Key Class: meta

class meta : public tools {
public:
    meta();
    ~meta();

    // Dataset information
    void set_cross_section(double xsec);
    double get_cross_section();

    void set_sum_of_weights(double sow);
    double get_sum_of_weights();

    void set_dataset_name(std::string name);
    std::string get_dataset_name();

    // Serialization
    void save(std::string path);
    void load(std::string path);

    meta_t data;
    std::string metacache_path;
};

Build System

All modules use CMake with:

add_library(module_name SHARED
    cxx/implementation.cxx
    # ... more sources
)

target_include_directories(module_name PUBLIC
    include/
)

target_link_libraries(module_name
    ROOT::Core
    ROOT::Tree
    # ... dependencies
)

Compilation

cd build
cmake ..
make -j$(nproc)

Or via pip:

pip install -e .

Dependencies

  • C++17 compiler (GCC 9+, Clang 10+)

  • ROOT 6.x

  • HDF5 (optional, for io module)

  • PyTorch C++ API (for model module)

See Also