template_synthesis.numpy.synthesis module¶

class template_synthesis.numpy.synthesis.SliceSynthesis(slice_grammage, ce_linear=True)¶

Bases: object

This class represents a single slice in the atmosphere in the template synthesis framework.

Typically, the grammage value of the slice is set to be the grammage at the bottom of the slice.

Parameters:¶

slice_grammage : int¶: The value of this slice, in g/cm2
ce_linear : bool, default=True¶: If True, use the linear variant for the CE corrections

grammage¶

The grammage of the slice

Type:¶: int

ce_linear¶

Whether to use the linear variant of the CE corrections

Type:¶: bool

Notes

This class is prone to removal in other versions of the software, so users are discouraged to interact with it directly. Instead, users are encouraged to interface with slices through the TemplateSynthesis class, whose functionality is more stable.

property antenna_parameters¶

Dictionary containing the antenna properties relating to the slice. The keys are:

‘amplitude_geo’ : the normalised geomagnetic amplitude spectrum
‘phase_geo’ : the phase spectrum of the geomagnetic component
‘amplitude_ce’ : the normalised charge-excess amplitude spectrum
‘phase_ce’ : the phase spectrum of the charge-excess component
‘distance’ : the distance of the antenna to the slice
‘viewing_angle’ : the viewing angle of the antenna with respect to the slice

calculate_arrival_time(shower: Shower)¶

Calculate the expected arrival time in each loaded antenna, given a shower geometry.

The antenna positions are calculated based on the loaded shower plane positions. These are projected to ground using the transformer from the provided shower.

Parameters:¶

shower : Shower¶: The shower containing the geometry

Returns:¶

observation_time – The arrival time (in internal units) in each antenna, shaped as (n_ant,)

Return type:¶

np.ndarray

Notes

The arrival time of the signal at an antenna depends both on the time it was emitted, which relates to the distance \(D\) between the slice and the antenna, as well as the travel time of the radio signal \(L\) from the slice to the antenna.

\[t_{obs} = \frac{ L \times n - D }{ c }\]

Because the shower front travels at nearly the speed of light, we do not need to correct the emission time \(D / c\) with the index of refraction.

calculate_geometry_phase_shift(shower: Shower)¶

Adjust the phase of the template to match the phase of the target geometry.

Parameters:¶

shower : Shower¶

Returns:¶

phase_correction – The phase correction for each antenna, shaped as (n_ant, n_freq)

Return type:¶

np.ndarray

create_interpolators(shower: Shower, frequencies)¶

Interpolate the correction factors to the amplitude spectrum at each frequency given in frequencies. Depending on the value of the SliceSynthesis.ce_linear attribute, this method will interpolate either use the charge-excess spectra without the quadratic term (if True), or the full log-parabolic spectra (if False).

Parameters:¶

shower : Shower¶: The Shower from which to use the parameters to evaluate the amplitude frequency spectra
frequencies : np.ndarray¶: The frequencies at which to evaluate the spectra, where the central frequency has already been removed

Returns:¶

interpolator_geo (scipy.interpolate.interp1d) – Interpolator object for the geomagnetic component
interpolator_ce (scipy.interpolate.interp1d) – Interpolator object for the charge-excess component

deserialise(data_dict)¶

Create the instance from saved data dictionary, as produced by serialise.

Parameters:¶

data_dict : dict¶: The data dictionary

get_normalisation_factors(shower: Shower)¶

Calculate the template synthesis normalisation factors, to remove geometric and shower parameter dependencies.

Parameters:¶

shower : Shower¶: The shower for which to calculate the normalisation factors.

Returns:¶

geo_factor (float) – The normalisation factor for the geomagnetic component.
ce_factor (float) – The normalisation factor for the charge-excess component.

get_spectra(delta_xmax, freq)¶

Retrieve the amplitude spectra at the specified frequencies, for a given \(\Delta X_{max}\) .

Parameters:¶

delta_xmax : float¶: The difference between the grammage of the slice and the shower \(X_{max}\).
freq : np.ndarray¶: The list of frequencies at which to evaluate the spectra

Returns:¶

spectrum_geo (np.ndarray) – The evaluated geomagnetic amplitude frequency spectrum, shaped as (# viewing angles, # freq).
spectrum_ce (np.ndarray) – The charge-excess spectrum
spectrum_ce_lin (np.ndarray) – The charge-excess spectrum, but evaluated without the quadratic (c) component.

make_template(origin: SlicedShower)¶

Process a SlicedShower into a template.

Parameters:¶

origin : template_synthesis.numpy.io.SlicedShower¶: The origin shower

map_template(target: Shower)¶

Map the template to a target profile, represented in a target Shower.

Calculates the trace for every antenna present in the template. The antennas are contained in the first dimension of the returned arrays.

Parameters:¶

target : Shower¶: The target Shower object, containing the longitudinal profile

Returns:¶

synthesised_geo (np.ndarray) – The geomagnetic trace for each antenna
synthesised_ce (np.ndarray) – The charge-excess trace for each antenna

serialise()¶

Prepare the slice to be saved to disk, collecting the necessary information into a dictionary.

Returns:¶: data – The dictionary containing the necessary data to reconstruct the slice
Return type:¶: dict

class template_synthesis.numpy.synthesis.TemplateSynthesis(freq_ar: list = None)¶

Bases: object

This class is the main interface for synthesising pulses.

The main workflow consists of creating an instance and reading in the spectral parameters from a particular file. Then one can pass a SlicedShower as an origin to the TemplateSynthesis.make_template method, which construct all the necessary arrays to perform the synthesis. To perform the synthesis, you then call the TemplateSynthesis.map_template method with a Shower instance, which should be equipped with a longitudinal profile and the parameters from the Gaisser-Hillas fit.

Parameters:¶

freq_ar : list, default=None¶: If not None, the spectral file with the numbers corresponding to the first, second and third element of the list will be read in during initialisation.

has_spectral_coefficients¶

Whether the spectral coefficients have been loaded

Type:¶: bool

geo¶

The spectral coefficients for the geomagnetic component

Type:¶: np.ndarray

ce¶

The spectral coefficients for the charge-excess component

Type:¶: np.ndarray

ce_lin¶

The spectral coefficients for the charge-excess component, but without the quadratic parameter

Type:¶: np.ndarray

atm¶

The atmosphere model from the origin shower, used to make the template

Type:¶: radiotools.atmosphere.models.Atmosphere

viewing_angles¶

The viewing angles (in units of Cherenkov angle) for which we have the spectral coefficients

Type:¶: np.ndarray

frequencies¶

The frequencies corresponding to the Fourier transform of the origin

Type:¶: np.ndarray

frequency_range¶

The minimum, maximum and central frequency for which the spectral parameters where fitted. This is read from the HDF5 file containing the spectral parameters.

Type:¶: tuple of float

antenna_information¶

The antenna information, containing the time axis, position and name of each antenna

Type:¶: np.ndarray

template_information¶

The information about the template, such as the name, geometry, magnetisation, \(X_{max}\), core and creation time

Type:¶: dict

slices¶

The list of slices in the template, each as a SliceSynthesis object

Type:¶: list

slices_grammage¶

The grammage at the bottom of each slice

Type:¶: list

Notes

It is implicitly assumed that the origin shower’s longitudinal profile is sampled with the same step size as the antennas are configured to observe (i.e. if the antennas are set up to observer slices with a thickness of 5 g/cm2, the longitudinal profile should also be sampled with a step size of 5 g/cm2 - which is set using the LONGI keyword in the CORSIKA input file).

get_antenna_names()¶

Get the names of all internal antennas.

Returns:¶: antenna_names
Return type:¶: list of str

get_origin_shower()¶

Create a minimal Shower object from the template information.

This function does not return the SlicedShower which was used to create the template. That one is not stored. Rather, the essential information such as geometry, core and magnetic field are stored in the TemplateSynthesis.template_information dictionary. This information is used to construct a minimal Shower object, which can be used for example to retrieve a transformer.

Returns:¶: origin – The minimal representation of the origin shower used to make the template
Return type:¶: Shower

get_time_axis()¶

Get the time axis for all antennas.

Returns:¶: time_axis – The time axis for each antenna, shaped as (# antennas, # time samples)
Return type:¶: np.ndarray

load_template(file_path)¶

Load the template from a saved state, as done by save_template.

Parameters:¶

file_path : str¶: The path to the .npz archive containing the template.

make_template(origin: SlicedShower, ce_linear=True)¶

Process a SlicedShower into a template.

Parameters:¶

origin : template_synthesis.numpy.io.SlicedShower¶: The origin shower
ce_linear : bool, default=True¶: Whether to use linear variant of the CE component correction

map_template(target: Shower)¶

Map the template to a target profile, represented in a target Shower.

Calculates the trace for every antenna present in the template. The antennas are contained in the first dimension of the returned arrays. If the target has not the same geometry of the template, the internal antenna positions are updated such to still have the same positions in the shower plane. It is recommended to only synthesise target showers with a lower zenith angle than the template, in which case the slices not present in the target will be cut.

Parameters:¶

target : Shower¶: The target Shower object, containing the longitudinal profile

Returns:¶

synthesised_geo (np.ndarray) – The synthesised geomagnetic trace in each antenna, shaped as (ant, samples)
synthesised_ce (np.ndarray) – The synthesised charge-excess trace in each antenna, shaped as (ant, samples)

Notes

The synthesised traces are the sum of all slices in the template, each of which is mapped to the target. If the geometry of the target and origin are different, there will be a mismatch in slices. If the target has a lower zenith, it will have fewer slices than the template. In this case we simply cut these last few slices. If on the other hand the target has a higher zenith angle, there will be slices which the template does not contain. While the algorithm will still work, the results will probably not be accurate as there is simply less signal being accounted for.

read_spectral_file(filename)¶

Read spectral parameters from a file with filename in the spectral_parameters/ directory.

Parameters:¶

filename : str¶: The name of the spectral parameters file

save_template(save_dir=None)¶

Save the internal state of the synthesis class to disk.

Parameters:¶

save_dir : str, default='template_synthesis/templates'¶

Returns:¶

status_code – If successful, returns 0

Return type:¶

int

slice_create_interpolators(my_slice_ind, shower: Shower, frequencies, use_ce_linear=None)¶

Get the interpolators for the corrections factors from the slice with index my_slice_ind.

The shower and frequencies are passed in as an arguments to the SliceSynthesis.create_interpolators method.

Parameters:¶

my_slice_ind : int¶: The index of the slice in the TemplateSynthesis.slices array. Should correspond to the grammage of the slice divided by the slice thickness minus one.
shower : Shower¶: The Shower from which to use the parameters to evaluate the amplitude frequency spectra
frequencies : np.ndarray¶: The frequencies to evaluate the amplitude frequency spectra
use_ce_linear : bool, default=None¶: If set, this can be used to override the ce_linear of the slice before evaluating the interpolators.If False, the charge-excess component spectra are evaluated using a log-parabola, i.e. with the c spectral parameter. If True, the component uses the linear variant.

Returns:¶

interpolator_geo (scipy.interpolate.interp1d) – Interpolator object for the geomagnetic component
interpolator_ce (scipy.interpolate.interp1d) – Interpolator object for the charge-excess component

slice_get_antenna_parameters(my_slice_ind)¶

Get the antenna array containing for each antenna the template amplitude and phase frequency spectra, for the geomagnetic and charge-excess components, as well as the distance and viewing angle.

Note that these last variables are changed with the information from the target shower during the mapping process, so beware when looking at these numbers.

The output is a structured array with the following fields:

name : the names of the antenna’s
position : the position of the antenna’s (in the NRR coordinate system)
amplitude_geo : the amplitude frequency spectra of the geomagnetic component
phase_geo : the phase frequency spectra of the geomagnetic component
amplitude_ce : the amplitude frequency spectra of the charge-excess component
phase_ce : the phase frequency spectra of the charge-excess component
distance : the distance from the slice to each antenna
viewing_angle : the viewing angle wrt to this slice of each antenna

Parameters:¶

my_slice_ind : int¶: The index of the slice in the TemplateSynthesis.slices array

Returns:¶

antenna_parameters – A structured array with the columns mentioned above

Return type:¶

np.ndarray

slice_get_normalisation_factors(my_slice_ind, shower: Shower)¶

Calculate the template synthesis normalisation factors, to remove geometric and shower parameter dependencies, according to

\[ \begin{align}\begin{aligned}geo_{factor} = n_{slice} * \sin( \alpha_{GEO} ) / \rho_{slice}\\ce_{factor} = n_{slice} * \sin( \theta^{Ch}_{slice} )\end{aligned}\end{align} \]

The shower parameter is used as argument to the SliceSynthesis.get_normalisation_factors().

Parameters:¶

my_slice_ind : int¶: The index of the slice in the TemplateSynthesis.slices array
shower : Shower¶: The shower for which to calculate the normalisation factors.

Returns:¶

geo_factor (float) – The normalisation factor for the geomagnetic component.
ce_factor (float) – The normalisation factor for the charge-excess component.

slice_get_spectra(my_slice_ind, delta_xmax, frequencies)¶

Retrieve the amplitude spectra at the specified frequencies, for a given \(\Delta X_{max}\) .

The delta_xmax and frequencies parameters are passed on to the SliceSynthesis.get_spectra function.

Parameters:¶

my_slice_ind : int¶: The index of the slice in the TemplateSynthesis.slices array
delta_xmax : float¶: The \(\Delta X_{max}\) for which to evaluate the spectral functions
frequencies : np.ndarray¶: The list of frequencies at which to calculate the spectra

Returns:¶

spectrum_geo (np.ndarray) – The evaluated geomagnetic amplitude frequency spectrum, shaped as (# viewing angles, # freq).
spectrum_ce (np.ndarray) – The charge-excess spectrum
spectrum_ce_lin (np.ndarray) – The charge-excess spectrum, but evaluated without the quadratic (c) component.

slice_map_template(my_slice_ind, target: Shower)¶

Map the template to a target profile, represented in a target Shower. Calculates the trace for every antenna present in the template. The antennas are contained in the first dimension of the returned arrays.

Parameters:¶

my_slice_ind : int¶: The index of the slice in the TemplateSynthesis.slices array
target : Shower¶: The target Shower object, containing the longitudinal profile

Returns:¶

synthesised_geo (np.ndarray) – The geomagnetic trace for each antenna
synthesised_ce (np.ndarray) – The charge-excess trace for each antenna

template_synthesis.numpy.synthesis.amplitude_function(params, frequencies, d_noise=0.0)¶

Calculate the amplitude frequency spectrum corresponding to the parameters params.

Parameters:¶

params : np.ndarray or list¶: The spectral parameters. If it is a multidimensional array, the first dimension must contain the parameters.
frequencies : np.ndarray¶: The values of the frequencies to evaluate in MHz - remove central frequency beforehand!
d_noise : float, default=0.0¶: The noise floor level

Return type:¶

The evaluated amplitude frequency spectrum