NuRadioReco.modules.io.coreas.coreasInterpolator module

class NuRadioReco.modules.io.coreas.coreasInterpolator.coreasInterpolator(corsika_evt)[source]

Bases: object

Interface to interpolate the electric field traces, as for example provided by CoREAS.

For the best results, ensure that the electric fields are in on-sky coordinates (this is the case when using the NuRadioReco.modules.io.coreas.coreas.read_CORSIKA7 function).

After having created the interpolator, you can either choose to interpolate the electric field traces or either the fluence (or both, but be careful to not mix them up). In order to do this, you first need to initialize the corresponding interpolator with the desired settings. Refer to the documentation of initialize_efield_interpolator and initialize_fluence_interpolator for more information. After initialization, you can call the interpolate_efield and interpolate_fluence functions to get the interpolated values.

Note that when trying to interpolate the electric fields of an air shower with a geomagnetic angle smaller than 15 degrees, the interpolator will fall back to using the closest observer position instead of performing the Fourier interpolation. Also, when attempting to extrapolate (ie get a value for a position that is outside the star shape pattern), the default behaviour is to return zeros when r > r_max and return a constant value when r <= r_min. This behaviour can be changed using the allow_extrapolation keyword argument when initialising the interpolator.

Parameters:

corsika_evtEvent: An Event object containing the CoREAS output, from read_CORSIKA7()

Attributes:

azimuth: The azimuth of the shower axis
efields_rotation_angle: The angle with which the e_theta and e_phi components of the electric field were rotated
magnetic_field_vector: The magnetic field vector stored inside the shower
starshape_radius: returns the maximal radius of the star shape pattern in the shower plane
starshape_radius_ground: returns the maximal radius of the star shape pattern on ground
zenith: The zenith of the shower axis

Methods

`get_closest_observer_efield`(...)	Returns the electric field of the closest observer position for an antenna position in the shower plane.
`get_empty_efield`()	Get an array of zeros in the shape of the electric field on the sky
`get_interp_efield_value`(position_on_ground)	Calculate the interpolated electric field given an antenna position on ground.
`get_interp_fluence_value`(position_on_ground)	Calculate the interpolated fluence for a given position on the ground.
`get_position_showerplane`(position_on_ground)	Transform the position of the antenna on ground to the shower plane.
`initialize_efield_interpolator`(...)	Initialise the efield signal interpolator
`initialize_fluence_interpolator`([quantity])	Initialise fluence interpolator.
`initialize_star_shape`()	Initializes the star shape pattern for interpolation, e.g. creates the arrays with the observer positions in the shower plane and the electric field.
`plot_fluence_footprint`([radius])	plots the interpolated values of the fluence in the shower plane
`set_fluence_of_efields`(function[, quantity])	Set the fluence quantity of all electric fields in the SimStation of the interpolator.

Notes

The interpolation method is based on the Fourier interpolation method described in Corstanje et al. (2023), JINST 18 P09005. The implementation lives in a separate package called cr-pulse-interpolator (this package is a optional dependency of NuRadioReco).

In short, the interpolation method works as follows: everything is done in the showerplane, where we expect circular symmetries due to the emission mechanisms. In case of fluence interpolation, we are working with a single value per observer position. The positions are expected to be in a starshape pattern, such that for each ring a Fourier series can be constructed for the fluence values. The components of the Fourier series are then radially interpolated using a cubic spline.

When interpolating electric fields, the traces are first transformed to frequency spectra. The amplitude in each frequency bin is then interpolated as a single value, as described above. The phases are also interpolated, making the relative timings consistent. To also get an absolute timing, one can provide the trace start times to also be interpolated (this is done in this implementation).

initialize_star_shape()[source]: Initializes the star shape pattern for interpolation, e.g. creates the arrays with the observer positions in the shower plane and the electric field.

property zenith: The zenith of the shower axis

property azimuth: The azimuth of the shower axis

property magnetic_field_vector: The magnetic field vector stored inside the shower

property starshape_radius: returns the maximal radius of the star shape pattern in the shower plane

property starshape_radius_ground: returns the maximal radius of the star shape pattern on ground

property efields_rotation_angle: The angle with which the e_theta and e_phi components of the electric field were rotated

get_empty_efield()[source]: Get an array of zeros in the shape of the electric field on the sky

set_fluence_of_efields(function, quantity=<electricFieldParameters.signal_energy_fluence: 4>)[source]

Set the fluence quantity of all electric fields in the SimStation of the interpolator.

Helper function to set the fluence of electric fields. These values can then be used for fluence interpolation.

One option to use as function is NuRadioReco.utilities.trace_utilities.get_electric_field_energy_fluence.

Parameters:

function: callable: The function to apply to the traces in order to calculate the fluence. Should take in a (3, n_samples) shaped array and return a float (or an array with 3 elements if you want the fluence per polarisation).
quantity: electric field parameter, default=efp.signal_energy_fluence: The parameter where to store the result of the fluence calculation