SPARKX: A Software Package for Analyzing Relativistic Kinematics in Collision Experiments

SPARKX is an open-source Python package developed to analyze simulation data from heavy-ion collision experiments. By offering a comprehensive suite of tools, SPARKX simplifies data analysis workflows, supports multiple formats such as OSCAR2013, and integrates seamlessly with SMASH and JETSCAPE/X-SCAPE. This paper describes SPARKX’s architecture, features, and applications and demonstrates its effectiveness through detailed examples and performance benchmarks. SPARKX enhances productivity and precision in relativistic kinematics studies.

💡 Research Summary

**
The manuscript introduces SPARKX, an open‑source Python package designed to streamline the analysis of heavy‑ion collision simulation data. Existing analysis frameworks such as ROOT and Rivet are primarily C++‑based and oriented toward experimental workflows, leaving theorists and phenomenologists to rely on ad‑hoc scripts that are often untested and difficult to maintain. SPARKX fills this gap by providing a coherent, Pythonic pipeline that covers data loading, filtering, physics analysis, and result visualization.

The architecture follows modern software engineering principles, notably Martin’s Clean Architecture and the SOLID design patterns. Core abstract classes (BaseLoader, BaseStorer) define generic interfaces for reading and storing event information, while concrete subclasses (OscarLoader, JetscapeLoader, ParticleObjectLoader) implement support for OSCAR2013, JETSCAPE/X‑SCAPE, and in‑memory particle lists. This abstraction enables easy addition of new file formats without touching the higher‑level analysis code.

Filtering is dictionary‑driven: users supply a mapping of filter names to parameters (e.g., charged particles, pT range, pseudo‑rapidity cut). Filters are applied sequentially, allowing complex selection criteria to be expressed in a single line. The filtered data are stored as Particle objects, each encapsulating four‑momentum, charge, and other attributes, which serve as the foundation for all subsequent analyses.

Physics analysis modules are grouped into four categories:

1. Event‑based analysis – BulkObservables computes rapidity, transverse momentum, pseudorapidity, and transverse mass spectra; CentralityClasses determines centrality bins from multiplicity; EventCharacteristics evaluates spatial eccentricities, supports various weighting schemes (number, energy, baryon number, charge, strangeness), and can smear particles onto a 3‑D lattice for hydrodynamic initial conditions; MultParticlePtCorrelations calculates multi‑particle pT correlations and cumulants up to eighth order.

2. Flow analysis – Six state‑of‑the‑art methods are implemented: EventPlaneFlow (with sub‑event resolution correction), LeeYangZeroFlow (zero‑of‑generating‑function technique), PCAFlow (principal‑component analysis of two‑particle correlations), QCumulantFlow (2nd, 4th, 6th order cumulants), ReactionPlaneFlow (theoretical constant‑reaction‑plane assumption), and ScalarProductFlow (scalar‑product method for symmetric systems). All share a common FlowInterface, ensuring a uniform API.

3. Jet analysis – JetAnalysis wraps the FastJet library, enabling jet finding, background subtraction, and extraction of jet observables directly from event data.

4. Utilities – Histogram provides a flexible container for binning and plotting; Jackknife offers statistical error estimation via resampling; Lattice3D manages three‑dimensional grids for spatial analyses.

Performance benchmarks compare SPARKX against ROOT/Rivet on identical OSCAR datasets (~10⁶ events). Despite being written in Python, SPARKX achieves comparable memory usage and only modestly higher runtimes (≈10–20 % slower), thanks to extensive use of NumPy vectorization, optional Cython acceleration, and multiprocessing support. The authors argue that the productivity gains, reproducibility, and ease of extension outweigh the slight speed penalty.

Testing is a first‑class concern: a comprehensive pytest suite covers unit, integration, and regression tests for every loader, filter, and analysis class. Continuous integration automatically validates new contributions, ensuring that the codebase remains robust as it evolves.

Two illustrative applications demonstrate real‑world utility. The first reproduces bulk observables and centrality classification from SMASH simulations, matching published experimental spectra. The second processes JETSCAPE output, performs jet reconstruction, and correlates jet properties with anisotropic flow coefficients, showcasing the package’s ability to combine disparate analyses in a single script.

The paper also outlines how to extend SPARKX to new data formats (e.g., HDF5) by subclassing the abstract loader/storer and registering the new class via entry points. Future development plans include GPU acceleration (Numba/CuPy), machine‑learning‑based event classification, and a standardized metadata schema to facilitate collaboration across experiments and theory groups.

In summary, SPARKX delivers a modular, well‑tested, and Python‑native framework for heavy‑ion collision analysis. By abstracting file I/O, providing a rich set of physics tools, and adhering to solid software design, it lowers the barrier for theorists to perform rigorous, reproducible analyses and positions itself as a valuable complement to existing C++‑based toolchains.