Complete Module Dependency Analysis

This document provides a complete recursive dependency analysis of all modules in the AnalysisG framework, identifying which modules depend on which others and organizing them into logical categories.

Overview

Total Source Files Analyzed: 339 files

  • 124 header files (.h, .cuh)

  • 215 source files (.cxx, .cu, .pyx)

Module Organization: 52 distinct modules across 11 categories

Module Categories

Core Templates (6 modules)

These are the fundamental template classes that users extend to implement their analyses.

event (3 files)

  • Location: src/AnalysisG/modules/event

  • Dependencies: meta, reconstruction, structs, templates, tools

  • Purpose: Event template for defining event-level selection logic

  • User extends: EventTemplate class

particle (6 files)

  • Location: src/AnalysisG/modules/particle

  • Dependencies: structs, templates, tools

  • Purpose: Particle template for physics object representation

  • User extends: ParticleTemplate class

graph (4 files)

  • Location: src/AnalysisG/modules/graph

  • Dependencies: structs, templates, tools

  • Purpose: Graph template for GNN inputs

  • User extends: GraphTemplate class

selection (4 files)

  • Location: src/AnalysisG/modules/selection

  • Dependencies: meta, structs, templates, tools

  • Purpose: Selection template for physics object filtering

  • User extends: SelectionTemplate class

metric (6 files)

  • Location: src/AnalysisG/modules/metric

  • Dependencies: meta, notification, plotting, structs, templates, tools

  • Purpose: Metric template for evaluation metrics

  • User extends: MetricTemplate class

model (5 files)

  • Location: src/AnalysisG/modules/model

  • Dependencies: notification, structs, templates

  • Purpose: Model template for PyTorch models

  • User extends: ModelTemplate class

Analysis Infrastructure (4 modules)

These modules orchestrate the analysis workflow and provide training infrastructure.

analysis (9 files)

  • Location: src/AnalysisG/modules/analysis

  • Dependencies: AnalysisG, generators, io, structs, templates, tools

  • Purpose: Main analysis orchestrator

  • Key Classes: Analysis

  • Coordinates: Event processing, selection application, graph building, model training

lossfx (5 files)

  • Location: src/AnalysisG/modules/lossfx

  • Dependencies: notification, structs, templates, tools

  • Purpose: Loss function and optimizer management

  • Provides: 20 loss functions, 6 optimizers, 2 LR schedulers

optimizer (2 files)

  • Location: src/AnalysisG/modules/optimizer

  • Dependencies: generators, metrics, structs, templates

  • Purpose: Training optimization logic

meta (2 files)

  • Location: src/AnalysisG/modules/meta

  • Dependencies: notification, structs, tools

  • Purpose: Metadata management and compilation

Data Management (4 modules)

These modules handle file I/O, data loading, and sample management.

io (5 files)

  • Location: src/AnalysisG/modules/io

  • Dependencies: meta, notification, structs, tools

  • Purpose: ROOT and HDF5 file I/O

  • Key Classes: root_reader, tree_reader, branch_reader

container (3 files)

  • Location: src/AnalysisG/modules/container

  • Dependencies: generators, meta, templates, tools

  • Purpose: Event/graph/selection collections

dataloader (4 files)

  • Location: src/AnalysisG/modules/dataloader

  • Dependencies: generators, io, notification, structs, templates, tools

  • Purpose: Batch loading for training

  • Features: CUDA memory management, multi-threading

sampletracer (2 files)

  • Location: src/AnalysisG/modules/sampletracer

  • Dependencies: container, generators, notification

  • Purpose: Sample metadata tracking

Utilities (4 modules)

Core utility modules providing fundamental functionality.

tools (4 files)

  • Location: src/AnalysisG/modules/tools

  • Dependencies: (none - foundation module)

  • Purpose: Base utility functions and classes

  • Note: This is a foundation module with no dependencies

structs (18 files)

  • Location: src/AnalysisG/modules/structs

  • Dependencies: tools

  • Purpose: Core data structures

  • Defines: particle_t, event_t, graph_t, settings_t, property_t, element_t

typecasting (5 files)

  • Location: src/AnalysisG/modules/typecasting

  • Dependencies: structs, tools

  • Purpose: Type conversion utilities

  • Defines: variable_t, write_t, merge/sum/contract operations

notification (2 files)

  • Location: src/AnalysisG/modules/notification

  • Dependencies: (none - foundation module)

  • Purpose: Logging and progress tracking

  • Note: Foundation module for messaging system

Visualization (3 modules)

Modules for plotting and result visualization.

plotting (2 files)

  • Location: src/AnalysisG/modules/plotting

  • Dependencies: notification, structs, tools

  • Purpose: General plotting utilities

roc (2 files)

  • Location: src/AnalysisG/modules/roc

  • Dependencies: plotting

  • Purpose: ROC curve generation

metrics (4 files)

  • Location: src/AnalysisG/modules/metrics

  • Dependencies: notification, structs, templates

  • Purpose: Metric computation utilities

Physics (1 module)

Specialized physics algorithms.

nusol (44 files)

  • Location: src/AnalysisG/modules/nusol

  • Dependencies: conuix, ellipse, notification, reconstruction, structs, templates, tools

  • Purpose: Neutrino reconstruction algorithms

  • Submodules:

    • conuix: Constraint-based solver

    • ellipse: Ellipse parameterization

    • nusol: Main reconstruction algorithms

    • multisol: Multiple solution handling

  • Algorithms:

    • Single neutrino W→lν (analytical)

    • Double neutrino ttbar→lνblνb (numerical)

    • Matrix-based constraint solving

PyC - C++/CUDA/Python Interface (7 modules)

High-performance CUDA kernels and C++/Python bindings.

pyc/cutils (6 files)

  • Location: src/AnalysisG/pyc/cutils

  • Dependencies: (none - standalone)

  • Purpose: C++ utilities and conversions

pyc/physics (5 files)

  • Location: src/AnalysisG/pyc/physics

  • Dependencies: (none - standalone)

  • Purpose: Physics calculations on GPU

  • Functions: P(), P2(), Beta(), M(), M2(), Mt(), Mt2(), Theta(), DeltaR()

pyc/operators (5 files)

  • Location: src/AnalysisG/pyc/operators

  • Dependencies: (none - standalone)

  • Purpose: Vector operations on GPU

  • Functions: Dot(), Cross(), CosTheta(), SinTheta(), Rx(), Ry(), Rz()

pyc/transform (5 files)

  • Location: src/AnalysisG/pyc/transform

  • Dependencies: (none - standalone)

  • Purpose: Coordinate transformations

  • Functions: PxPyPzE2PtEtaPhiE(), PtEtaPhiE2PxPyPzE()

pyc/graph (8 files)

  • Location: src/AnalysisG/pyc/graph

  • Dependencies: (none - standalone)

  • Purpose: Graph algorithms on GPU

  • Functions: page_rank(), page_rank_reconstruction()

pyc/nusol (12 files)

  • Location: src/AnalysisG/pyc/nusol

  • Dependencies: (none - standalone)

  • Purpose: GPU-accelerated neutrino reconstruction

  • Implements: CUDA kernels for analytical and numerical solvers

pyc/interface (7 files)

  • Location: src/AnalysisG/pyc/interface

  • Dependencies: templates, tools

  • Purpose: Python/C++ interface layer

Events (7 variants)

Concrete event implementations for different analyses.

events/bsm_4tops (6 files)

  • Location: src/AnalysisG/events/bsm_4tops

  • Dependencies: bsm_4tops, templates

  • Purpose: BSM 4-top search event class

events/exp_mc20 (6 files)

  • Location: src/AnalysisG/events/exp_mc20

  • Dependencies: exp_mc20, templates

  • Purpose: Experimental MC20 campaign events

events/ssml_mc20 (8 files)

  • Location: src/AnalysisG/events/ssml_mc20

  • Dependencies: ssml_mc20, templates

  • Purpose: Semi-supervised ML MC20 events

events/gnn (6 files)

  • Location: src/AnalysisG/events/gnn

  • Dependencies: inference, templates

  • Purpose: GNN inference events

Graphs (3 variants)

Concrete graph implementations for GNN inputs.

graphs/bsm_4tops (9 files)

  • Location: src/AnalysisG/graphs/bsm_4tops

  • Dependencies: bsm_4tops, templates

  • Purpose: Graph representation for 4-top analysis

graphs/exp_mc20 (6 files)

  • Location: src/AnalysisG/graphs/exp_mc20

  • Dependencies: exp_mc20, templates

  • Purpose: Graph representation for MC20 experimental data

graphs/ssml_mc20 (6 files)

  • Location: src/AnalysisG/graphs/ssml_mc20

  • Dependencies: ssml_mc20, templates

  • Purpose: Graph representation for SSML analysis

Metrics (2 implementations)

Concrete metric implementations.

metrics/accuracy (4 files)

  • Location: src/AnalysisG/metrics/accuracy

  • Dependencies: templates

  • Purpose: Accuracy metric for classification

metrics/pagerank (4 files)

  • Location: src/AnalysisG/metrics/pagerank

  • Dependencies: templates

  • Purpose: PageRank metric for graph analysis

Models (2 implementations)

Concrete model implementations.

models/grift (4 files)

  • Location: src/AnalysisG/models/grift

  • Dependencies: templates

  • Purpose: GRaph Interaction FineTuning model

models/RecursiveGraphNeuralNetwork (3 files)

  • Location: src/AnalysisG/models/RecursiveGraphNeuralNetwork

  • Dependencies: templates

  • Purpose: Recursive GNN architecture

Core (15 files)

core (15 files)

  • Location: src/AnalysisG/core

  • Dependencies: (none - standalone)

  • Purpose: Core Python interface layer

  • Contains: All template base classes in Cython

Complete Dependency Graph

Foundation Modules (No Dependencies)

These modules form the foundation and have no dependencies on other modules:

  • tools - Base utilities

  • notification - Logging system

  • core - Python interface

  • pyc/cutils - C++ utilities

  • pyc/physics - GPU physics

  • pyc/operators - GPU operators

  • pyc/transform - GPU transforms

  • pyc/graph - GPU graph algorithms

  • pyc/nusol - GPU neutrino solver

Level 1 Dependencies (Depend only on Foundation)

These modules depend only on foundation modules:

  • structs → tools

  • plotting → notification, structs, tools

  • meta → notification, structs, tools

Level 2 Dependencies

  • typecasting → structs, tools

  • io → meta, notification, structs, tools

  • roc → plotting

Level 3+ Dependencies (Complex)

  • particle → structs, templates, tools

  • graph → structs, templates, tools

  • selection → meta, structs, templates, tools

  • event → meta, reconstruction, structs, templates, tools

  • model → notification, structs, templates

  • metrics → notification, structs, templates

  • lossfx → notification, structs, templates, tools

  • metric → meta, notification, plotting, structs, templates, tools

  • container → generators, meta, templates, tools

  • optimizer → generators, metrics, structs, templates

  • sampletracer → container, generators, notification

  • dataloader → generators, io, notification, structs, templates, tools

  • nusol → conuix, ellipse, notification, reconstruction, structs, templates, tools

  • pyc/interface → templates, tools

  • analysis → AnalysisG, generators, io, structs, templates, tools

Circular Dependencies

None detected. The module structure forms a proper directed acyclic graph (DAG).

Dependency Chain Analysis

Longest Dependency Chain

The longest dependency chain is through the analysis module:

User Code
  ↓
analysis
  ↓
io, dataloader, container
  ↓
meta, structs, templates
  ↓
tools, notification

Maximum depth: 4 levels

Critical Path Modules

These modules are dependencies for many other modules:

  1. tools - 15 modules depend on it

  2. structs - 14 modules depend on it

  3. templates - 13 modules depend on it

  4. notification - 10 modules depend on it

  5. meta - 6 modules depend on it

Build Order Recommendation

Based on the dependency analysis, modules should be built in this order:

Phase 1: Foundation (parallel build possible)

  • tools

  • notification

  • core

  • pyc/cutils, pyc/physics, pyc/operators, pyc/transform, pyc/graph, pyc/nusol

Phase 2: Core Structures (after Phase 1)

  • structs

Phase 3: Utilities (after Phase 2)

  • typecasting

  • plotting

  • meta

Phase 4: I/O and Templates (after Phase 3)

  • io

  • roc

Phase 5: Template Classes (after Phase 4)

  • particle

  • graph (template)

  • selection

  • event

  • model

  • metrics (module)

  • lossfx

  • metric

Phase 6: Infrastructure (after Phase 5)

  • container

  • optimizer

  • pyc/interface

Phase 7: Advanced (after Phase 6)

  • sampletracer

  • dataloader

  • nusol

Phase 8: Orchestration (after Phase 7)

  • analysis

Phase 9: Concrete Implementations (after Phase 8, parallel build possible)

  • events/bsm_4tops, events/exp_mc20, events/ssml_mc20, events/gnn

  • graphs/bsm_4tops, graphs/exp_mc20, graphs/ssml_mc20

  • metrics/accuracy, metrics/pagerank

  • models/grift, models/RecursiveGraphNeuralNetwork

Module File Statistics

Module File Counts

Module

File Count

Category

nusol

44

Physics (largest module)

structs

18

Utilities

core

15

Core Python Interface

pyc/nusol

12

PyC CUDA/Python

graphs/bsm_4tops

9

Graphs

analysis

9

Analysis Infrastructure

events/ssml_mc20

8

Events

pyc/graph

8

PyC CUDA/Python

pyc/interface

7

PyC CUDA/Python

events/bsm_4tops

6

Events

events/exp_mc20

6

Events

events/gnn

6

Events

graphs/exp_mc20

6

Graphs

graphs/ssml_mc20

6

Graphs

metric

6

Core Templates

particle

6

Core Templates

pyc/cutils

6

PyC CUDA/Python

io

5

Data Management

lossfx

5

Analysis Infrastructure

model

5

Core Templates

pyc/operators

5

PyC CUDA/Python

pyc/physics

5

PyC CUDA/Python

pyc/transform

5

PyC CUDA/Python

typecasting

5

Utilities

Usage in Analysis

Typical User Workflow

  1. Define Templates (user extends):

    • EventTemplate → Custom event class

    • ParticleTemplate → Custom particle types

    • SelectionTemplate → Physics object selections

    • GraphTemplate → Graph structure for GNN

    • ModelTemplate → PyTorch model

    • MetricTemplate → Evaluation metrics

  2. Configure Analysis:

    from AnalysisG import Analysis

analysis = Analysis()
analysis.add_event_template(MyEvent)
analysis.add_selection_template(MySelection)
analysis.add_graph_template(MyGraph)
analysis.add_model(MyModel)
analysis.add_metric_template(MyMetric)

  3. Execute Pipeline:

    analysis.start()  # Orchestrates all modules

Internal Dependency Flow

When analysis.start() is called, it coordinates these modules in order:

  1. io - Read ROOT/HDF5 files

  2. event - Build EventTemplate instances

  3. selection - Apply SelectionTemplate

  4. graph - Build GraphTemplate for GNN

  5. dataloader - Create training batches

  6. model - Execute PyTorch training

  7. optimizer - Update model weights

  8. lossfx - Compute loss and backprop

  9. metric - Evaluate performance

  10. plotting, roc - Generate visualizations

  11. io (write) - Save results to ROOT/HDF5

Summary

The AnalysisG framework consists of:

  • 52 distinct modules

  • 339 source files (124 headers, 215 sources)

  • 11 logical categories

  • 4-level maximum dependency depth

  • No circular dependencies

  • 9-phase recommended build order

All modules are organized in a clean dependency hierarchy with foundation modules at the bottom and high-level orchestration at the top. The modular design allows for flexible extension while maintaining clear separation of concerns.

See Also

  • /modules/core_templates/overview - Core template classes

  • /technical/build/cmake - CMake build system

  • Analysis Pipeline and Workflow - Analysis pipeline workflow