Readdressing the contribution of photonuclear reactions to the muon content of extensive air showers: a heuristic approach

Nickolay S. Martynenko^1, 2, *

¹ Lomonosov Moscow State University, 1–2 Leninskie Gory, Moscow 119991, Russia
² Institute for Nuclear Research of the Russian Academy of Sciences, 60th October Anniversary Prospect 7a, Moscow 117312, Russia
^* Corresponding author: [email protected]

About This Repository

This repository provides datasets corresponding to the findings presented in the paper:
arXiv:2512.12481 (submitted to Phys. Rev. D).

Dataset Structure

The repository contains the following main components:

1. Monte-Carlo/ — Monte Carlo (MC) Datasets

These datasets were produced by the author using CONEX v7.80 for extensive air shower (EAS) simulations.

• README.md
  Brief documentation for the datasets.

• HadCascade.parquet
  Dataset for the high‑energy hadronic cascade development (proton‑induced EAS).

• ElmCascade.parquet
  Dataset for the electromagnetic cascade development (photon‑induced EAS).

• MixCascade.parquet
  Dataset used for model validation (photon‑ and nucleus‑induced EAS).

2. utils/demo.py — Python Demo Script

A demonstration script for reading the MC datasets and verifying their integrity.

Requirements

To work with the datasets, you will need:

• Git LFS — for downloading large Parquet files.
• Python 3 (recommended: 3.12.7) — for running the demo script.
• Awkward Array (recommended: 2.8.4) — for handling the structured data.

Note: The datasets were created and tested using Python 3.12.7 and Awkward Array 2.8.4. Using these versions ensures reproducibility.

How to Get Started

1. Install prerequisites

   • Install Git LFS and Python 3.12.7
   • Consider using Miniconda to manage dependencies easily
   • Install Awkward Array (e.g. pip install awkward==2.8.4)

2. Clone the repository

   git clone https://github.com/Nickolay-Martynenko/Photonuclear-Interactions-in-EAS.git

3. Navigate to the repository directory:

   cd Photonuclear-Interactions-in-EAS

4. Download the Parquet files:

   git lfs pull

   Note: total size is approximately 0.68 GB. This may take some time depending on your internet speed

5. Run the demo script:

   python3 utils/demo.py

   Expected output (3 lines in terminal):

   73728 * {Fragment: string, Shower_Id: uint32, Shower_Log10Energy: float32,
   Shower_NumLeadingInteractions: uint8, Shower_NumSecondaryParticles: uint16,
   LeadingInteractions: var * {ParticleId: uint16, Log10Energy: float32, SlantDepth: float32,
   NumSecondaryParticles: uint16}, SecondaryParticles: var * {LeadingInteractionId: uint8,
   ParticleId: uint16, Log10Energy: float32}}
   
   19456 * {Fragment: string, Shower_Id: uint32, Shower_Log10Energy: float32,
   PNR_Log10Energy_BinEdges: 49 * float32, MuonSlantDepth: 201 * float32,
   MuonNumber: 48 * 201 * float32}
   
   239616 * {Shower_Id: uint32, Shower_Log10Energy: float32, Shower_ParticleId: uint16,
   PNR_XsMod2Std: float32, PNR_Log10Energy_Std2Mod: float32, MuonSlantDepth: 201 * float32,
   MuonNumber: 201 * float32}
   

License

The code and datasets in this repository are released under the MIT License. See LICENSE for details.

Citation

If you use this dataset or any other result of this study in your research, please cite the original paper:

@article{Martynenko:2025zxj,
    author = "Martynenko, Nickolay S.",
    title = "{Readdressing the contribution of photonuclear reactions to the muon content of extensive air showers: a heuristic approach}",
    eprint = "2512.12481",
    archivePrefix = "arXiv",
    primaryClass = "astro-ph.HE",
    reportNumber = "INR-TH-2025-022",
    month = "12",
    year = "2025"
}