Simulation output

Saving files

The files are saved in .npy format. Each file contains Nevents events (trajectories). The Nevents parameter is passed to the particle generator and defines how many particles are generated per file.

Another parameter related to saving is Nfiles, which defines how many files are created. In total, Nfiles files will be saved, each containing Nevents trajectories. The base name for the saved files is defined by the Output variable.

Flux = {"Nevents": 200, **other_params}
Nfiles = 20
Output = "saving_files_example"

The resulting files follow the naming structure: saving_files_example_i.npy, where i is the file index (starting from 1).

Reading files

Each file contains a list of dictionaries, where each dictionary corresponds to a single particle event. The dictionary has the following keys:

  • Track

  • Particle

  • BC

  • Child

  • Additions (only present for the Magnetosphere region)

import numpy as np

events = np.load("reading_files_example_1.npy", allow_pickle=True)
# len(events) equals the number of particles in the file

# Iterate over each event
for event in events:
    # event is a dictionary with the structure described above
    print(event)

Dictionary structure

  1. Track – contains trajectory data:

    • Coordinates – particle trajectory points

    • Velocities – velocity vectors at each point

    • Efield – electric field along the trajectory

    • Bfield – magnetic field along the trajectory

    • Angle – scattering angle relative to the previous point

    • Path – cumulative path length

    • Density – amount of matter traversed: \(\int \rho \, dr\), where \(\rho\) is the density at each point

    • Clock – elapsed time from the start

    • Energy – kinetic energy along the trajectory

  2. Particle – particle properties:

    • M – mass

    • Z – charge number

    • PDG – PDG code

    • T0 – initial kinetic energy

    • Gen – particle generation (primary, secondary, etc.)

  3. BC – break conditions:

    • WOut – break code indicating why the simulation stopped (see BreakCode)

  4. Child – array of secondary particles produced in interactions. Each element has the same structure as described above.

  5. Additions – additional calculated parameters (see GTSimulator class for details).

Plotting trajectories

To plot the trajectory of the i-th particle, use events[i]["Track"]["Coordinates"]. Coordinates are in the default GT units (meters). You may convert them to other units using the gtsimulation.Global.consts.Units module.

import numpy as np
import matplotlib.pyplot as plt
from Global.consts import Units

# Load data
events = np.load("reading_files_example_1.npy", allow_pickle=True)

# Plot only the first event for clarity
event = events[0]

# Convert to desired units (e.g., kpc)
R = event["Track"]["Coordinates"] / Units.kpc
X, Y, Z = R[:, 0], R[:, 1], R[:, 2]

# Create 3D plot
fig = plt.figure()
ax = fig.add_subplot(111, projection='3d')
ax.set_xlabel("X [kpc]")
ax.set_ylabel("Y [kpc]")
ax.set_zlabel("Z [kpc]")

# Plot trajectory and markers
ax.plot(X, Y, Z, label="Trajectory")
ax.scatter(X[0], Y[0], Z[0], label="Start point")
ax.scatter(X[-1], Y[-1], Z[-1], label="End point")

ax.legend()
plt.show()