Reference

class dionpy.IonFrame(dt, position, hbot=60, htop=1000, nlayers=100, nside=32, rdeg_offset=5, name=None, iriversion=20, autocalc=True, echaim=False, _pool=None)

A model of the ionosphere for a specific moment in time. Given a position, calculates electron density and temperature in the ionosphere in all visible directions using International Reference Ionosphere (IRI) model. The calculated model can estimate ionospheric attenuation and refraction in a given direction defined by elevation and azimuth angles.

Parameters:

  • dt – Date/time of the model.

  • position – Geographical position of an observer. Must be a tuple containing latitude [deg], longitude [deg], and elevation [m].

  • nside (default: 32) – Resolution of healpix grid.

  • hbot (default: 60) – Lower limit in [km] of the layer of the ionosphere.

  • htop (default: 1000) – Upper limit in [km] of the layer of the ionosphere.

  • nlayers (default: 100) – Number of sub-layers in the ionospheric layer for intermediate calculations.

  • rdeg_offset (default: 5) – Extends the angular horizon distance of calculated ionosphere in [degrees].

  • iriversion (default: 20) – Version of the IRI model to use. Must be a two digit integer that refers to the last two digits of the IRI version number. For example, version 20 refers to IRI-2020.

  • echaim (default: False) – Use ECHAIM model for electron density estimation.

  • autocalc (default: True) – If True - the model will be calculated immediately after definition.

Methods

get_init_dict()

Returns a dictionary containing the initial parameters for the IonLayer object.

Note:

  • The default value for autocalc is False.

ed(alt, az, layer=None)
Parameters:

  • alt (float | ndarray) – Elevation of an observation.

  • az (float | ndarray) – Azimuth of an observation.

  • layer (Optional[int], default: None) – Number of sublayer from the precalculated sublayers. If None - an average over all layers is returned.

Return type:

float | ndarray

Returns:

Electron density in the layer.

plasfreq(alt, az, layer=None, angular=True)
Parameters:

  • alt (float | ndarray) – Elevation of an observation.

  • az (float | ndarray) – Azimuth of an observation.

  • layer (Optional[int], default: None) – Number of sublayer from the precalculated sublayers. If None - an average over all layers is returned.

  • angular (bool, default: True) – If True - angular plasma frequency is calculated.

Return type:

float | ndarray

Returns:

Plasma frequency in [Hz].

edll(lat, lon, layer=None)
Parameters:

  • lat (float | ndarray) – Latitude of a point.

  • lon (float | ndarray) – Longitude of a point.

  • layer (Optional[int], default: None) – Number of sublayer from the precalculated sublayers. If None - an average over all layers is returned.

Return type:

float | ndarray

Returns:

Electron density in the layer.

et(alt, az, layer=None)
Parameters:

  • alt (float | ndarray) – Elevation of an observation.

  • az (float | ndarray) – Azimuth of an observation.

  • layer (Optional[int], default: None) – Number of sublayer from the precalculated sublayers. If None - an average over all layers is returned.

Return type:

float | ndarray

Returns:

Electron temperature in the layer.

etll(lat, lon, layer=None)
Parameters:

  • lat (float | ndarray) – Latitude of a point.

  • lon (float | ndarray) – Longitude of a point.

  • layer (Optional[int], default: None) – Number of sublayer from the precalculated sublayers. If None - an average over all layers is returned.

Return type:

float | ndarray

Returns:

Electron density in the layer.

raytrace(alt, az, freq, col_freq='default', troposphere=True, height_profile=False, _pool=None)

Starts the raytracing procedure and calculates integrated refraction, absorption and emission in all specified directions. As a shortcut to this method one can call the IonFrame(…) directly.

Parameters:

  • alt (float | ndarray) – Altitude (elevation) of observation in [deg].

  • az (float | ndarray) – Azimuth of observation in [deg].

  • freq (float) – Frequency of observation in [MHz].

  • col_freq (str, default: 'default') –

    Model of colission frequency. Available options:

    ”default” == “aggrawal”

    ”aggrawal”: https://ui.adsabs.harvard.edu/abs/1979P%26SS…27..753A/abstract

    ”nicolet”: [Nicolet, M. 1953, JATP, 3, 200]

    ”setty”: [Setty, C. S. G. K. 1972, IJRSP, 1, 38]

  • troposphere (bool, default: True) – Where to include the tropospheric refraction effect.

  • height_profile (bool, default: False) – If True, returns arrays of attenuation and emission before integration and a cumulative history of refraction.

Return type:

Tuple[ndarray, ndarray, ndarray]

Returns:

(refraction, attenuation, emission)

save(saveto='./ionframe')

Save the model to HDF file.

Parameters:

saveto (str, default: './ionframe') – Path and name of the file.

classmethod load(path)

Load a model from file.

Parameters:

path (str) – Path to a file (file extension is not required).

Returns:

IonModel recovered from a file.

plot_ed(gridsize=200, layer=None, cmap='plasma', **kwargs)

Visualize electron density in the ionospheric layer.

Parameters:

  • gridsize (int, default: 200) – Grid resolution of the plot.

  • layer (Optional[int], default: None) – A specific layer to plot. If None - an average of all layers is calculated.

  • cmap (default: 'plasma') – A colormap to use in the plot.

  • kwargs – See dionpy.plot_kwargs.

Returns:

A matplotlib figure.

plot_plasfreq(layer, gridsize=200, cmap='plasma', **kwargs)

Visualize plasma frequency in the ionospheric layer.

Parameters:

  • gridsize (int, default: 200) – Grid resolution of the plot.

  • layer (int) – A specific layer to plot. If None - an average of all layers is calculated.

  • cmap (default: 'plasma') – A colormap to use in the plot.

  • kwargs – See dionpy.plot_kwargs.

Returns:

A matplotlib figure.

plot_et(gridsize=200, layer=None, **kwargs)

Visualize electron temperature in the ionospheric layer.

Parameters:

  • gridsize (int, default: 200) – Grid resolution of the plot.

  • layer (Optional[int], default: None) – A specific sub-layer to plot. If None - an average of all layers is calculated.

  • kwargs – See dionpy.plot_kwargs.

Returns:

A matplotlib figure.

plot_atten(freq, troposphere=True, gridsize=200, cmap='plasma', cblim=None, **kwargs)

Visualize ionospheric attenuation.

Parameters:

  • freq (float) – Frequency of observation in [Hz].

  • troposphere (bool, default: True) – If True - the troposphere refraction correction will be applied before calculation.

  • gridsize (int, default: 200) – Grid resolution of the plot.

  • cmap (default: 'plasma') – A colormap to use in the plot.

  • cblim (default: None) – Colorbar limits.

  • kwargs – See dionpy.plot_kwargs.

Returns:

A matplotlib figure.

plot_emiss(freq, troposphere=True, gridsize=200, cblim=None, **kwargs)

Visualize ionospheric emission.

Parameters:

  • freq (float) – Frequency of observation in [Hz].

  • troposphere (bool, default: True) – If True - the troposphere refraction correction will be applied before calculation.

  • gridsize (int, default: 200) – Grid resolution of the plot.

  • cblim (default: None) – Colorbar limits.

  • kwargs – See dionpy.plot_kwargs.

Returns:

A matplotlib figure.

plot_refr(freq, troposphere=True, gridsize=200, cmap='plasma_r', cblim=None, **kwargs)

Visualize ionospheric refraction.

Parameters:

  • freq (float) – Frequency of observation in [Hz].

  • troposphere (bool, default: True) – If True - the troposphere refraction correction will be applied before calculation.

  • gridsize (int, default: 200) – Grid resolution of the plot.

  • cmap (str, default: 'plasma_r') – A colormap to use in the plot.

  • cblim (default: None) – Colorbar limits.

  • kwargs – See dionpy.plot_kwargs.

Returns:

A matplotlib figure.

plot_troprefr(gridsize=200, cblim=None, **kwargs)

Visualize tropospheric refraction.

Parameters:

  • gridsize (default: 200) – Grid resolution of the plot.

  • cblim (default: None) – Colorbar limits.

  • kwargs – See dionpy.plot_kwargs.

Returns:

A matplotlib figure.

troprefr(alt)

Approximation of the refraction in the troposphere recommended by the ITU-R: https://www.itu.int/dms_pubrec/itu-r/rec/p/R-REC-P.834-9-201712-I!!PDF-E.pdf

Parameters:

alt (float | ndarray) – Elevation of observation(s) in [deg].

Return type:

float | ndarray

Returns:

Refraction in the troposphere in [deg].

class dionpy.IonModel(dt_start, dt_end, position, mpf=15, nside=64, hbot=60, htop=500, nlayers=500, rdeg_offset=5, iriversion=20, echaim=False, autocalc=True)

A dynamic model of the ionosphere. Uses a sequence of IonFrame objects to interpolate ionospheric refraction and attenuation in the specified time range.

Parameters:

  • dt_start – Start date/time of the model.

  • dt_end – End date/time of the model.

  • position – Geographical position of an observer. Must be a tuple containing latitude [deg], longitude [deg], and elevation [m].

  • mpf (default: 15) – Number of minutes per frame.

  • nside (default: 64) – Resolution of healpix grid.

  • hbot (default: 60) – Lower limit in [km] of the layer of the ionosphere.

  • htop (default: 500) – Upper limit in [km] of the layer of the ionosphere.

  • nlayers (default: 500) – Number of sub-layers in the ionospheric layer for intermediate calculations.

  • rdeg_offset (default: 5) – Extends the angular horizon distance of calculated ionosphere in [degrees].

  • iriversion (default: 20) – Version of the IRI model to use. Must be a two digit integer that refers to the last two digits of the IRI version number. For example, version 20 refers to IRI-2020.

  • echaim (default: False) – Use ECHAIM model for electron density estimation.

  • autocalc (default: True) – If True - the model will be calculated immediately after definition.

Methods

at(dt, recalc=False)
Parameters:

  • dt (datetime) – Date/time of the frame.

  • recalc (bool, default: False) – If True - the IonFrame object will be precisely calculated. If False - an interpolation of two closest frames will be used.

Return type:

IonFrame

Returns:

IonFrame at specified time.

save(saveto='./ionmodel')

Save the model to a file.

Parameters:

saveto (str, default: './ionmodel') – Path to directory with name to save the model.

classmethod load(path)

Load a model from file.

Parameters:

path (str) – Path to a file (file extension is not required).

Return type:

IonModel

Returns:

IonModel recovered from a file.

animate(target, saveto='./', freq=None, gridsize=100, fps=20, duration=5, codec='libx264', **plot_kwargs)

Calculates the dynamic evolution of specified parameters and generates an animated visualization.

Parameters:

  • target (Union[str, List[str]]) – Parameter or list of parameters to calculate. Options include: “atten” - Attenuation (integrated) “refr” - Refraction (integrated) “emiss” - Emission (integrated) “edens” - Electron density (height average) “etemp” - Electron temperature (height average)

  • saveto (str, default: './') – Location of the output files. Defaults to the script execution directory (“./”).

  • freq (Optional[float], default: None) – Frequency of observation.

  • gridsize (int, default: 100) – Grid resolution of calculated data.

  • fps (int, default: 20) – Frames per second.

  • duration (int, default: 5) – Total duration of the video in seconds.

  • codec (str, default: 'libx264') – Specify the codec for ffmpeg to use.