# Simulations based on Monte Carlo EAS ground particle data¶

Perform simulations of CORSIKA air showers on a cluster of stations

This simulation uses a HDF5 file created from a CORSIKA simulation with the store_corsika_data script. The shower is ‘thrown’ on the cluster with random core positions and azimuth angles.

Example usage:

>>> import tables
>>> from sapphire import GroundParticlesSimulation, ScienceParkCluster
>>> data = tables.open_file('/tmp/test_groundparticle_simulation.h5', 'w')
>>> cluster = ScienceParkCluster()
>>> sim = GroundParticlesSimulation('corsika.h5', 500, cluster, data,
...                                 '/', 10)
>>> sim.run()

class sapphire.simulations.groundparticles.GroundParticlesSimulation(corsikafile_path, max_core_distance, *args, **kwargs)

Simulation initialization

Parameters: corsikafile_path – path to the corsika.h5 file containing the groundparticles. max_core_distance – maximum distance of shower core to center of cluster.
finish()

Clean-up after simulation

generate_shower_parameters()

Generate shower parameters like core position, energy, etc.

For this groundparticles simulation, only the shower core position and rotation angle of the shower are generated. Do not interpret these parameters as the position of the cluster, or the rotation of the cluster! Interpret them as shower parameters.

Returns: dictionary with shower parameters: core_pos (x, y-tuple) and azimuth.
simulate_detector_response(detector, shower_parameters)

Simulate detector response to a shower.

Checks if leptons have passed a detector. If so, it returns the number of leptons in the detector and the arrival time of the first lepton passing the detector.

Parameters: detector – Detector for which the observables will be determined. shower_parameters – dictionary with the shower parameters.
simulate_detector_mips_for_particles(particles)

Simulate the detector signal for particles

Parameters: particles – particle rows with the p_[x, y, z] components of the particle momenta.
simulate_trigger(detector_observables)

Simulate a trigger response.

This implements the trigger as used on HiSPARC stations: - 4-detector station: at least two high or three low signals. - 2-detector station: at least 2 low signals.

Parameters: detector_observables – list of dictionaries, each containing the observables of one detector. True if the station triggers, False otherwise.
simulate_gps(station_observables, shower_parameters, station)

Simulate gps timestamp.

Parameters: station_observables – dictionary containing the observables of the station. shower_parameters – dictionary with the shower parameters. station – sapphire.clusters.Station for which to simulate the gps timestamp. station_observables updated with gps timestamp and trigger time.
get_particles_in_detector(detector, shower_parameters)

Get particles that hit a detector.

Particle ids 2, 3, 5, 6 are electrons and muons, id 4 is no longer used (were neutrino’s).

The detector is approximated by a square with a surface of 0.5 square meter which is not correctly rotated. In fact, during the simulation, the rotation of the detector is undefined. This is faster than a more thorough implementation.

The CORSIKA simulation azimuth is used for the projection because the cluster is rotated such that from the perspective of the rotated detectors the CORSIKA showers come from the desired azimuth. In the simulation frame the CORSIKA shower azimuth remains unchanged.

Parameters: detector – Detector for which to get particles. shower_parameters – dictionary with the shower parameters.
class sapphire.simulations.groundparticles.GroundParticlesGammaSimulation(corsikafile_path, max_core_distance, *args, **kwargs)

Simulation which includes signals from gamma particles in the shower

Simulation initialization

Parameters: corsikafile_path – path to the corsika.h5 file containing the groundparticles. max_core_distance – maximum distance of shower core to center of cluster.
simulate_detector_response(detector, shower_parameters)

Simulate detector response to a shower.

Checks if particles have passed a detector. If so, it returns the number of particles in the detector and the arrival time of the first particle passing the detector.

Parameters: detector – Detector for which the observables will be determined. shower_parameters – dictionary with the shower parameters.
get_particles_in_detector(detector, shower_parameters)

Get particles that hit a detector.

Particle ids 2, 3, 5, 6 are electrons and muons, id 4 is no longer used (were neutrino’s).

The detector is approximated by a square with a surface of 0.5 square meter which is not correctly rotated. In fact, during the simulation, the rotation of the detector is undefined. This is faster than a more thorough implementation.

Detector height is ignored!

Parameters: detector – Detector for which to get particles. shower_parameters – dictionary with the shower parameters.
simulate_detector_mips_for_gammas(particles)

Simulate the detector signal for gammas

Parameters: particles – particle rows with the p_[x, y, z] components of the particle momenta.
class sapphire.simulations.groundparticles.DetectorBoundarySimulation(corsikafile_path, max_core_distance, *args, **kwargs)

More accuratly simulate the detection area of the detectors.

Take the orientation of the detectors into account and use the exact detector boundaries. This requires a slightly more complex query which is a bit slower.

Simulation initialization

Parameters: corsikafile_path – path to the corsika.h5 file containing the groundparticles. max_core_distance – maximum distance of shower core to center of cluster.
get_particles_in_detector(detector, shower_parameters)

Simulate the detector detection area accurately.

First particles are filtered to see which fall inside a non-rotated square box around the detector (i.e. sides of 1.2m). For the remaining particles a more accurate query is used to see which actually hit the detector. The advantage of using the square is that column indexes can be used, which may speed up queries.

Parameters: detector – Detector for which to get particles. shower_parameters – dictionary with the shower parameters.
get_line_boundary_eqs(p0, p1, p2)

Get line equations using three points

Given three points, this function computes the equations for two parallel lines going through these points. The first and second point are on the same line, whereas the third point is taken to be on a line which runs parallel to the first. The return value is an equation and two boundaries which can be used to test if a point is between the two lines.

Parameters: p0,p1 – (x, y) tuples on the same line. p2 – (x, y) tuple on the parallel line. value1, equation, value2, such that points satisfying value1 < equation < value2 are between the parallel lines.

Example:

>>> get_line_boundary_eqs((0, 0), (1, 1), (0, 2))
(0.0, 'y - 1.000000 * x', 2.0)

class sapphire.simulations.groundparticles.ParticleCounterSimulation(corsikafile_path, max_core_distance, *args, **kwargs)

Do not simulate mips, just count the number of particles.

Simulation initialization

Parameters: corsikafile_path – path to the corsika.h5 file containing the groundparticles. max_core_distance – maximum distance of shower core to center of cluster.
simulate_detector_mips(n, theta)

A mip for a mip, count number of particles in a detector.

class sapphire.simulations.groundparticles.FixedCoreDistanceSimulation(corsikafile_path, max_core_distance, *args, **kwargs)

Shower core at a fixed core distance (from cluster origin).

Parameters: core_distance – distance of shower core to center of cluster.

Simulation initialization

Parameters: corsikafile_path – path to the corsika.h5 file containing the groundparticles. max_core_distance – maximum distance of shower core to center of cluster.
classmethod generate_core_position(r_max)

Generate a random core position on a circle

Parameters: r_max – Fixed core distance, in meters. Random x, y position on the circle with radius r_max.
class sapphire.simulations.groundparticles.GroundParticlesSimulationWithoutErrors(corsikafile_path, max_core_distance, *args, **kwargs)

This simulation does not simulate errors/uncertainties

This results in perfect timing (first particle through detector) and particle counting for the detectors.

Simulation initialization

Parameters: corsikafile_path – path to the corsika.h5 file containing the groundparticles. max_core_distance – maximum distance of shower core to center of cluster.
class sapphire.simulations.groundparticles.MultipleGroundParticlesSimulation(corsikaoverview_path, max_core_distance, min_energy, max_energy, *args, **kwargs)

Use multiple CORSIKA simulated air showers in one run.

Simulations will be selected from the set of available showers. Each time an energy and zenith angle is generated a shower is selected from the CORSIKA overview. Each shower is reused multiple times to take advantage of caching, and to reduce IO stress.

Warning

This simulation loads a new shower often it is therefore more I/O intensive than GroundParticlesSimulation. Do not run many of these simulations simultaneously!

Simulation initialization

Parameters: corsikaoverview_path – path to the corsika_overview.h5 file containing the available simulations. max_core_distance – maximum distance of shower core to center of cluster. min_energy,max_energy – upper and lower shower energy limits, in eV.
DATA = '/data/hisparc/corsika/data/{seeds}/corsika.h5'
finish()

Clean-up after simulation

generate_shower_parameters()

Generate shower parameters like core position, energy, etc.

For this groundparticles simulation, only the shower core position and rotation angle of the shower are generated. Do not interpret these parameters as the position of the cluster, or the rotation of the cluster! Interpret them as shower parameters.

Returns: dictionary with shower parameters: core_pos (x, y-tuple) and azimuth.
select_simulation()

Generate parameters for selecting a CORSIKA simulation

Returns: simulation row from a CORSIKA Simulations table.