smiet.core module¶

Main class to run SMIET on

class smiet.core.SMIETRun(site: str = 'base', backend: str = 'numpy')¶

Bases: object

Main class to run SMIET on. The idea of this class is so that all users can easily apply SMIET to their own analyses.

Main Features:¶

• generating templates from origin showers, in particular from generated origin shower libraries

• loading templates from existing template libraries

• loading target showers from existing Coreas simulations

• generating target showers from user-provided longitudinal profiles

• synthesizing target showers from origin shower templates + target showers, with interpolation (by default)

• retrieving time traces, frequency spectra, and fluences for synthesized showers

The user is expected to give the site in which SMIET will apply on, and the backend (jax or numpy).

generate_target_showers(target_grammage: ndarray, target_longs: list[ndarray], target_xmaxs: ndarray, target_nmaxs: ndarray, target_zeniths: ndarray, target_azimuths: ndarray | None = None, target_cores: ndarray | None = None) → None¶

Generate and set target showers based on user-provided longitudinal profiles and geometries.

Parameters:¶

target_grammagenp.ndarray

The grammage slices corresponding to the provided longitudinal profiles. Should be a numpy array of shape (N,) where N is the number of grammage slices.

target_longslist[np.ndarray]

A list of longitudinal profiles for each target shower. Each profile should be a numpy array of shape (N,) where N is the number of grammage slices. The number of grammage slices need not match those in the templates, as interpolation will be performed internally.

Note that in previous versions, the xmax and nmax were inferred from the longitudinal profile. This is now passed explicitly to reduce errors from fitting.

target_xmaxsnp.ndarray

The xmax values for each target shower. Should be a numpy array of shape (M,) where M is the number of target showers.

target_nmaxsnp.ndarray

The nmax values for each target shower. Should be a numpy array of shape (M,) where M is the number of target showers.

target_zenithsnp.ndarray

The zenith angles for each target shower in radians. Should be a numpy array of shape (M,) where M is the number of target showers.

target_azimuthsUnion[np.ndarray, None], default=None

The azimuth angles for each target shower in radians. Should be a numpy array of shape (M,) where M is the number of target showers. If None, azimuths will be set to 0 degrees by default.

target_coresUnion[np.ndarray, None], default=None

The core positions for each target shower in internal units. Should be a numpy array of shape (M, 2) where M is the number of target showers and each entry contains the (x, y) core position in meters. If None, cores will be set to (0, 0) by default.

generate_templates(origin_shower_repo: str, template_repo: str, reset: bool = False) → None¶

Generate templates from a list of origin showers generated from the origin shower library.

This is meant to be ran once to generate the templates used for the origin shower library.

Parameters:¶

origin_shower_repostr

The path to the origin shower repository containing all the origin showers to generate templates from.

template_repostr

The path to the repository to save the generated templates.

resetbool, default=False

Whether to reset and regenerate all templates even if they already exist. Default is False.

get_fluence(xmax: float, zenith: float, geoce: bool = True, slice_grammage: float | None = None) → tuple[ndarray, ndarray]¶

Get the fluence for a given synthesised shower.

Parameters:¶

xmaxfloat

The xmax of the target shower to retrieve fluence for.

zenithfloat

The zenith angle of the target shower to retrieve fluence for.

geocebool, default=True

Whether to return traces in the geomagnetic + charge-excess emissions. If False, returns in the shower plane coordinate system.

slice_grammageUnion[float, None], default=None

The grammage slice to retrieve traces for. If None, retrieves traces at all slices. If traces are only synthesised at the ground, then that will be returned instead.

get_origin_properties(name: str = 'xmaxs') → dict¶

Return the properties of each origin shower

get_spectrum(xmax: float, zenith: float, ant_name: str | None = None, geoce: bool = True, slice_grammage: float | None = None) → tuple[ndarray, ndarray]¶

Get the frequency spectrum for a given synthesised shower and antenna name (optional).

Parameters:¶

xmaxfloat

The xmax of the target shower to retrieve spectrum for.

zenithfloat

The zenith angle of the target shower to retrieve spectrum for.

ant_nameUnion[str, None], default=None

The name of the antenna to retrieve spectrum for. If None, all antennas will be returned.

geocebool, default=True

Whether to return traces in the geomagnetic + charge-excess emissions. If False, returns in the shower plane coordinate system.

slice_grammageUnion[float, None], default=None

The grammage slice to retrieve traces for. If None, retrieves traces at all slices. If traces are only synthesised at the ground, then that will be returned instead.

Returns:¶

tuple[np.ndarray, np.ndarray]

A tuple containing: - spectrum: np.ndarray of shape (N_pol, N_antennas, N_freqbins, Nslices)

The frequency spectrum either in geo/ce components (if geoce is True) or in vxB/vxvxB components (if geoce is False).

• freq_grid: np.ndarray of shape (N_freqbins,)

  The frequency axis corresponding to the spectrum.

If ant_name is not None, N_antennas will be 1 and the corresponding antenna spectrum will be returned.

get_target_properties(name: str = 'xmaxs') → dict¶

Return the properties of each target shower

get_traces(xmax: float, zenith: float, ant_name: str | None = None, geoce: bool = True, slice_grammage: float | None = None) → tuple[ndarray, ndarray, ndarray]¶

Get the time traces for a specific target shower.

Parameters:¶

xmaxfloat

The xmax of the target shower to retrieve traces for.

zenithfloat

The zenith angle of the target shower to retrieve traces for.

ant_nameUnion[str, None], default=None

The name of the antenna to retrieve traces for. If None, all antennas will be returned.

The nomenclature for antenna names is given as ‘ant_r{r}_phi{phi}`, where phi is the azimuthal angle in degrees and r is the radial distance in meters.

The avaliable antenna names can be found in the antenna_labels attribute after synthesis.

geocebool, default=True

Whether to return traces in the geomagnetic + charge-excess emissions. If False, returns in the shower plane coordinate system.

slice_grammageUnion[float, None], default=None

The grammage slice to retrieve traces for. If None, retrieves trace at the ground. If traces are only synthesised at the ground, the argument will default to None.

Returns:¶

tuple[np.ndarray, np.ndarray, np.ndarray]

A tuple containing: - traces: np.ndarray of shape (N_pol, N_antennas, N_timebins, n_slices)

The traces either in geo/ce components (if geoce is True) or in vxB/vxvxB components (if geoce is False).

• times: np.ndarray of shape (N_antennas, N_timebins, n_slices)

  The time axes corresponding to each antenna trace.

• antenna_positions: np.ndarray of shape (N_antennas, 3)

  The positions of each antenna in meters in the shower plane.

If ant_name is not None, N_antennas will be 1 and the corresponding antenna trace & time will be returned.

get_truths(xmax: float, zenith: float, mode: str = 'fluence', geoce: bool = True) → tuple[ndarray, ndarray, ndarray]¶

Return the truth values for a given synthesised shower.

Note that this is only available if the target showers were loaded from Coreas simulations. Otherwise, an error will be raised.

Parameters:¶

xmaxfloat

The xmax of the target shower to retrieve truths for.

zenithfloat

The zenith angle of the target shower to retrieve truths for.

modestr, default=”fluence”

The mode of truth values to retrieve. Options are “fluence”, “spectrum”, or “traces”.

geocebool, default=True

Whether to return traces in the geomagnetic + charge-excess emissions. If False, returns in the shower plane coordinate system.

load_coreas_showers(coreas_shower_paths: list[str], gdas_atmosphere_paths: list[str] | None = None)¶

Load target showers in the form of existing coreas simulations.

Parameters:¶

coreas_shower_pathslist[str]

A list of paths to each coreas simulation in HDF5 format. Each path corresponds to a single target shower.

gdas_atmosphere_pathsUnion[list[str], None], default=None

The path to the GDAS atmosphere for each simulation. Default is None, where the model set globally is used. If provided, the entries and length of this list must match the length of coreas_shower_paths.

load_templates(template_repo: str, xmax_range: tuple | None = None, zenith_range: tuple | None = None, randomize: bool = False, dcore_min: float = 10.0) → None¶

Load the templates for synthesis. This will load the necessary templates which will be used for the run.

This will automatically load the templates if they are available, otherwise new templates will be generated from origin showers.

The origin shower library will be used by default. If you want to perform synthesis with a single origin shower (e.g. for testing purposes), use the synthesize_with_single_origin function instead.

If you only want to load a subset of xmax / zenith values for the synthesis, you can do so by specifying the ranges. If no ranges are provided, all available templates will be loaded.

Parameters:¶

template_repostr

The path to the repository containing the origin shower library (templates).

xmax_rangeUnion[tuple, None], default=None

The range of xmax values to load templates for. If None, all xmax values will be loaded.

zenith_rangeUnion[tuple, None], default=None

The range of zenith angles to load templates for. If None, all zenith angles will be loaded.

randomizebool, default=False

Whether to randomly select one template per configuration. Default is False.

dcore_minfloat, default=10.0 * units.m

The minimum core distance to consider for antennas in the template synthesis. Antennas closer than this distance to the shower core will be removed from the template to avoid artifacts in the synthesis.

Returns:¶

None

synthesize_showers(interpolation: bool = True, slices: bool = False) → None¶

Run the synthesis for all loaded target showers.

This will perform the interpolation synthesis method by default, where the combination of two synthesis, weighted by some function, will be used. It is most adviced to use this method, so only disable the interpolation if you need to.

Parameters:¶

interpolationbool, default=True

Whether to use interpolation synthesis method. If False, the nearest neighbor synthesis object will be used.

slicesbool, default=False

Whether to synthesise traces for all slices. If False, only synthesises at ground level.

synthesize_with_single_origin(origin_shower_path: str, target_long: ndarray, target_grammage: ndarray, target_zenith: float, target_azimuth: float = 0.0, target_core: ndarray = array([0., 0., 0.])) → tuple[ndarray, ndarray, ndarray]¶

Perform synthesis with a single origin shower.

This function is mostly for testing purposes, but is available if users want to do this.

Parameters:¶

origin_shower_pathstr

The path to the origin shower to use for synthesis.

target_longnp.ndarray

The longitudinal profile of the target shower.

target_grammagenp.ndarray

The grammage slices corresponding to the provided longitudinal profile.

target_zenithfloat

The zenith angle of the target shower.

target_azimuthfloat, default=0.0

The azimuth angle of the target shower. Default is 0.0 degrees.

target_corenp.ndarray, default=np.array([0.0, 0.0, 0.0])

The core position of the target shower in meters. Default is (0.0, 0.0, 0.0).

Returns:¶

np.ndarray

The synthesised time traces for the target shower and the time axes.