Accessing Particle Reference Data in High Energy Physics with Kotlin

1. Introduction

Modern experimental high-energy physics (HEP) is increasingly defined by large data volumes and complex, software-driven analysis pipelines. Physics analyses rely on both experimentally recorded data and simulated data samples. Simulated data are produced through multiple stages, including event generation and detector simulation, while experimental data undergo reconstruction and physics analysis. Across these workflows, consistent and authoritative particle reference information is required. As a result, structured and machine-readable particle data have become a critical dependency of contemporary HEP software.

Particle reference data are deeply embedded throughout the high-energy physics software stack. Detector simulation frameworks such as GEANT4 [1,2,3] depend on this information to accurately model particle interactions with detector materials. Event generators, including PYTHIA [4], HERWIG [5,6], and SHERPA [7], incorporate reference particle data to simulate hard scattering processes and subsequent event evolution. Reconstruction and analysis frameworks, typically built around ROOT [8] based workflows, rely on these data for a range of tasks in object identification and physics interpretation. In all these contexts, particle reference data serve as an implicit but essential component.

The Particle Data Group (PDG) collaboration provides the authoritative source of particle properties through the Review of Particle Physics [9]. The PDG serves as the de facto standard source for particle properties, fundamental interactions, and related metadata, ensuring coherence across theoretical and experimental studies. To support programmatic access to PDG data, several mechanisms are currently available. These include a REST-based API provided by the PDG [10], the PDG Python API, distributed as the pdg package [11], the scikit-hep/particle [12] Python package, part of the broader Scikit-HEP [13] project, and downloadable PDG database files.

At the same time, the Kotlin [14] programming language is gaining increasing attention as a candidate for the development of next-generation scientific software. Kotlin combines expressive language constructs with full compatibility with the Java Virtual Machine (JVM) ecosystem. The potential of Kotlin for scientific computing has been demonstrated across a growing number of projects: KMath, a Kotlin-based mathematics library [15]; a REST API and web interface for the Event Metadata System of the BM@N experiment [16]; detector simulation software for calculating the total muon flux observed by the Muon Monitor experiment [17]; VisionForge, a framework for 3D visualization of particle physics experiments [18]; and DataForge, a framework for automated data acquisition and storage [19], with demonstrated application to the Troitsk nu-mass experiment in the search for sterile neutrinos [20]. Despite this potential, there is currently no Kotlin implementation for structured access to PDG particle reference data.

This work presents a Kotlin solution, KParticle, designed to fill this gap. The goal of the presented solution is to enable the use of particle data in Kotlin-based HEP software while adhering to modern software development principles. The following sections of this paper describe the KParticle architecture, its implementation details, and application scenarios, demonstrating its potential in high-energy physics research.

2. Background

The PDG Review of Particle Physics is updated annually and published every two years in the journal HEP. It includes a compilation and evaluation of measurements of the properties of known elementary particles and summarizes searches for hypothetical new particles. For the 2024 edition, 2,717 new measurements from 869 papers were added, in addition to 46,838 measurements from 12,909 papers that first appeared in previous editions. 120 individual review articles discuss topics such as Higgs bosons, supersymmetry, Big Bang nucleosynthesis, probability, statistics, accelerators and detectors [21].

The particle data provided by PDG is distributed in various formats. These include a downloadable SQLite [22,23] database file.

The SQLite distribution integrates the complete PDG dataset into a single relational database [24]. This schema contains many interrelated tables that describe particle identifiers, particle properties, decay channels, experimental measurements, bibliographic references, and supporting documentation. The main tables of the database are presented in Table 1, and the relational structure and foreign key dependencies are shown in Figure 1. The figure provides a summary of the database schema and the columns of each table. The arrows indicate foreign key relationships. The columns in bold indicate constraints.

3. KParticle

At a high-level, the architecture is a three-tier model consisting of a client tier, a middle-tier, and a data source tier (Figure 2, left).

The client tier includes external client applications, which are HEP software that depends on particle data. These may include simulation frameworks or analysis tools written in Kotlin. Clients interact exclusively with the public interfaces provided by KParticle. To ensure encapsulation, direct access to the database is intentionally prohibited.

The middle tier is represented by the KParticle. This layer acts as an intermediary between clients and the underlying data source. It encapsulates domain logic related to particle properties, identifiers, etc., and provides a stable programming interface independent of data storage details.

The data source tier consists of a PDG SQLite database file. This database provides particle data and is accessible only through mechanisms implemented in the middle tier.

This separation ensures that the application code is independent of the database schema and storage format, thus increasing portability and reproducibility. Since the PDG database is updated every two years, with new versions replacing older ones, KParticle, by encapsulating all versioning logic and providing version-aware APIs, protects client applications from disruptive schema changes.

The internal structure of the KParticle is further illustrated in (Figure 2, right), which shows its internal decomposition into logically distinct layers.

The public API layer provides the interface through which client applications interact with the KParticle. The API is designed to remain stable between different versions, even as the underlying layers evolve.

Immediately beneath the public API is a service layer that acts as an intermediary and coordinates the processing of requests. It coordinates incoming API calls and data access components, applying any necessary validation, transformation, or workflow management, while remaining independent of data persistence issues.

The repository layer abstracts all data retrieval operations through repositories and data access objects (DAO).

The connection layer is responsible for loading database files and configuring JDBC.

Based on this conceptual diagram, Figure 3 provides a detailed view of the internal layers of KParticle at the class level. On the left side (Figure 3, left) the system is organized into five main layers, and each layer is represented by a set of classes associated with its functional role. The repository layer is further decomposed into internal components – repository, DAO, query, mapper, and model – highlighting the separation between domain modeling, query construction, data access abstraction, and object mapping. Surrounding classes such as ParticleService, PdgIdRepository, ParticleRepository, PdgId, Particle, PdgIdDAO, ParticleDAO, PdgIdQuery, ParticleQuery, and DBConnection are positioned to indicate that they belong to the main layer.

On the right side (Figure 3, right) is a UML class diagram. The KParticle class delegates operations to the ParticleService class, which interacts with repository classes such as PdgIdRepository and ParticleRepository. Each repository uses the corresponding DAO and Query classes (PdgIdDao, ParticleDao, PdgIdQuery, ParticleQuery) to build and execute database queries. To provide a connection to the database, DAO objects use DBConnection. Dashed arrows labeled “Use“ indicate usage dependencies, clarifying the direction of interaction between classes. It should be noted that the diagram is representative rather than exhaustive; for clarity, only a sufficient subset of classes is shown, and the remaining classes are omitted.

4. Results

KParticle is implemented as a modular library in Kotlin that follows the structure described in the previous section and is built and managed using the Gradle [25] build system. Using Kotlin ensures full compatibility with the JVM ecosystem, and Gradle provides structured dependency management, automated testing support, and a reproducible build configuration. The resulting artifact can be integrated as a standard dependency into JVM-based HEP software projects.

Several representative use cases illustrate the applicability of KParticle to real-world HEP workflows.

1.

Extraction of particle properties.

Access to the basic properties of particles specified by the PDG identifier, such as mass, electric charge, lifetime, and spin, is a fundamental requirement for software in the field of high energy physics. Typical applications include initializing event records, setting simulation parameters, and validating particle definitions used in various software components.

2.

Integration with Monte Carlo Simulations.

Monte Carlo (MC) models used in high-energy physics require accurate data-driven input parameters to describe particle properties—such as energy, momentum, type—to accurately simulate primary interactions and subsequent particle trajectories.

3.

Preparing a dataset for machine learning applications.

Machine learning applications in high energy physics often require numerical feature vectors derived from particle properties such as mass, charge, spin, and lifetime.

The following examples demonstrate the practical use of KParticle. For instance, a particle can be retrieved by name as follows:

Similarly, particle retrieval can be executed using a Monte Carlo ID (MCID), followed by the verification of its particle classification.

For example, historical particle mass measurements can be retrieved and visualized using Plotly.kt, a Kotlin wrapper for the popular Plotly visualization library [26].

The example below illustrates the energy loss of muons in standard rock as a function of kinetic energy.

Figure 4. Historical measurements of the muon mass.

Figure 4. Historical measurements of the muon mass.

Figure 5. Muon energy loss in standard rocks as a function of kinetic energy.

Figure 5. Muon energy loss in standard rocks as a function of kinetic energy.

5. Conclusions

This work presents KParticle, a software solution implemented in Kotlin that provides access to particle reference data in the JVM ecosystem. The system is designed with an emphasis on ease of use, modularity, and scalability, meeting the requirements of modern scientific computing. Its layered architecture ensures that client applications interact exclusively with high-level particle abstractions without access to database-specific implementation details. This solution can be used in scenarios involving analysis, validation, simulation, and machine learning. Further development will focus on integration with modeling and machine learning.