Utilities

The spine.utils package collects the cross-cutting helpers that support the driver, model, reconstruction, and analysis layers. It includes optional-dependency handling, logging, factories, reconstruction-specific utilities, and numerical helpers that do not belong to a single pipeline stage.

Utility functions and tools used across the SPINE package.

This module contains reusable utility functions organized into several categories:

Core utilities:

• conditional for optional imports such as ROOT, LArCV, MinkowskiEngine, and PyTorch.

• factory and logger for application infrastructure.

• globals for deprecated shared-constant compatibility.

Scientific utilities:

• cluster and gnn for clustering and graph operations.

• particles, pid, tracking, and vertex for reconstruction helpers.

• energy_loss and optical for detector-physics calculations.

Developer utilities:

• docstring for docstring inheritance.

• jit for Numba-backed acceleration.

• stopwatch for timing and profiling.

• unwrap and weighting for data processing.

Most utilities are designed to be framework-agnostic where possible, with PyTorch-specific functionality clearly separated and conditionally imported.

Core Utilities

conditional	Lazy access to optional third-party dependencies.
docstring	Docstring inheritance utilities.
factory	Contains functions needed to instantiate a class from a dictionary.
globals	Deprecated compatibility shim for legacy global constants imports.
logger	SPINE logging setup and rank-aware output filtering.
stopwatch	Simple stopwatch class to track execution times of various processes.

Physics And Reconstruction Utilities

energy_loss	Module of functions that approximate the energy loss of particles through matter.
match	Functions to find the best overlaps between point sets.
metrics	Various metrics used to evaluate clustering.
optical	Defines objects and methods related to optical information.
particles	Particle truth information post-processors.
pid	Module with functions/classes used to identify particle species.
ppn	Module which contains utility function to process PPN information.
tracking
vertex
weighting	Module which contains methods to compute class weights.

Numerical And Graph Utilities

cluster
gnn
inference	Module with helper functions to run inference on a model configuration.
jit	JIT compilation decorators using Numba for performance optimization.
torch	PyTorch utilities organized by functionality.