smiet.numpy.synthesis module

class smiet.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 : smiet.numpy.io.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 : smiet.numpy.io.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 : smiet.numpy.io.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

get_normalisation_factors(shower: Shower)

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

Parameters:
shower : smiet.numpy.io.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 : smiet.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 : smiet.numpy.io.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

class smiet.numpy.synthesis.TemplateSynthesis(freq_ar: list = [30, 500, 100])

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=[30, 500, 100]

The frequency range (min, max, central) in MHz for which to load the spectral parameters. Currently available options are:

  • [30, 500, 100] : can be used for most general purposes and experiments

  • [30, 80, 50] : a smaller sub-band which can be used for experiments such as LOFAR, AERA, etc

The default value is [30, 500, 100].

NOTE: The frequency range provided should not be multiplied by units.MHz, as this is done internally!

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

n_samples

The number of time samples in the traces

Type:

int

delta_t

The time step between each time sample in the traces

Type:

float

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

grammages

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:

smiet.numpy.io.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, gdas_file=None)

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

Parameters:
file_path : str

The path to the .hdf5 archive containing the template.

gdas_file : str, default=None

If not None, the Atmosphere will be created using this GDAS file. Otherwise, the Atmosphere will be created using the model and n0 parameters stored in the template file. If the model number is not available in radiotools, this will crash.

make_template(origin: SlicedShower, ce_linear=True)

Process a SlicedShower into a template.

Parameters:
origin : smiet.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 : smiet.numpy.io.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.

map_template_to_slices(target: Shower)

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

alculates the trace for every antenna present in the template at each slice. 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 : smiet.numpy.io.Shower

The target Shower object, containing the longitudinal profile

Returns:

  • synthesised_geo_slices (np.ndarray) – The synthesised geomagnetic trace in each antenna, shaped as (ant, samples, slices)

  • synthesised_ce_slices (np.ndarray) – The synthesised charge-excess trace in each antenna, shaped as (ant, samples, slices)

Notes

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

remove_antennas(dcore_min: float = 5) → None

Dummy function to match jax version for now.

In the future, this should be removed and should be implemented in SlicedShower instead.

save_template(save_dir: str = '/home/kwatanabe/Projects/radio-ift/smiet-cr-synthesis/smiet/numpy/../templates/numpy', template_file=None)

Save the internal state of the synthesis class to disk.

Parameters:
save_dir : str, default='smiet/templates/numpy'

template_file : str, default=None

The name of the file to save the template as. If None, the template will be saved as <template_name>.hdf5 in the save_dir directory.

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 : smiet.numpy.io.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 : smiet.numpy.io.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 : smiet.numpy.io.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

smiet.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