Antennas - ephemerista.comms.antennas

The antennas.py module.

This module provides several classes for modelling radio antennas and their gain patterns.

class ephemerista.comms.antennas.Antenna(*, designFrequency=None, boresightVector=(0.0, 0.0, 1.0))

Abstract base class for antenna models.

abstractmethod beamwidth(frequency)

Return the half-power beamwidth of the antenna for a given frequency.

Return type:

float

property boresight_array: ndarray

boresight vector.

Type:

numpy.ndarray

abstractmethod gain(frequency, angle)

Return the gain of the antenna for a given frequency and elevation.

Return type:

float

model_config: ClassVar[ConfigDict] = {'alias_generator': <function to_camel>, 'populate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

viz_cone_3d(frequency, sc_state, beamwidth_deg=None, cone_length=None, opacity=0.5, name=None, **kwargs)

Plot the antenna’s beamwidth as a 3D cone.

Notes

The beamwidth is optional. If None, the antenna’s beamwidth will be used. All keywords arguments are passed to plotly’s go.Surface method to tune the plot.

Return type:

Surface

class ephemerista.comms.antennas.ComplexAntenna(*, designFrequency=None, boresightVector=(0.0, 0.0, 1.0), type='complex', pattern)

The ComplexAntenna class.

This class models a complex antenna with a specified antenna gain pattern.

beamwidth(frequency)

Return the half-power beamwidth of the antenna for the given frequency.

Return type:

float

gain(frequency, angle)

Return the gain of the antenna for the given frequency and elevation.

Return type:

ndarray

model_config: ClassVar[ConfigDict] = {'alias_generator': <function to_camel>, 'populate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

peak_gain(frequency)

Return the peak gain of the antenna for the given frequency.

Return type:

float

plot_contour_2d(frequency, sc_state, gain_dynamic=75)

Create a folium interactive map with the antenna beam contour.

References

Largely inspired by https://github.com/python-visualization/folium/issues/958#issuecomment-427156672.

Return type:

Map

plot_pattern(frequency, fig_style='polar', trace_name=None, *, relative_to_peak=False)

Plot the antenna gain pattern.

Return type:

Scatterpolar | Scatter | None

to_geo_df(frequency, sc_state)

Return a dataframe containing the ground coordinates of the antenna beam (i.e. gain).

Return type:

DataFrame

ephemerista.comms.antennas.DIV_BY_ZERO_LIMIT = 1e-06

Represents the lowest gain value in linear representation, because zero gain would lead to an error when converting to dB. This value represents a signal strength in dB so low that no link will probably be possible.

class ephemerista.comms.antennas.DipolePattern(*, type='dipole', length)

The DipolePattern class.

This class models the gain pattern of a dipole antenna.

beamwidth(frequency)

Return the beamwidth of the dipole pattern.

Notes

Always returns 180 degrees, because the concept of beamwidth is undefined with dipole antennas: a dipole antennas has several main lobes of sometimes different widths.

Return type:

float

directivity(frequency)

Return the directivity of the dipole pattern for a given frequency.

Return type:

float

gain(frequency, angle)

Return the gain of the dipole pattern for a given frequency and elevation.

Return type:

ndarray

gain_pattern(frequency, angle)

Return the gain relative to the peak gain, in linear units, between 0 and 1.

References

Source 1: Slide 17 of https://www.brown.edu/research/labs/mittleman/sites/brown.edu.research.labs.mittleman/files/uploads/lecture25.pdf Source 2: https://www.antenna-theory.com/antennas/dipole.php Source 3: https://en.wikipedia.org/wiki/Dipole_antenna#Short_dipole Source 4: https://www.antenna-theory.com/antennas/shortdipole.php.

Return type:

ndarray

model_config: ClassVar[ConfigDict] = {'alias_generator': <function to_camel>, 'populate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

peak_gain(frequency)

Return the peak gain of the dipole pattern for a given frequency.

Return type:

float

class ephemerista.comms.antennas.GaussianPattern(*, type='gaussian', diameter, efficiency)

The GaussianPattern class.

This class models a Gaussian gain pattern.

beamwidth(frequency)

Return the half-power beamwidth of the antenna for a given frequency in radians.

References

https://uk.mathworks.com/help/satcom/ref/satcom.satellitescenario.transmitter.gaussianantenna.html.

Return type:

float

gain(frequency, angle)

Return the gain of the Gaussian antenna for a given frequency and elevation.

References

https://uk.mathworks.com/help/satcom/ref/satcom.satellitescenario.transmitter.gaussianantenna.html.

Return type:

ndarray

model_config: ClassVar[ConfigDict] = {'alias_generator': <function to_camel>, 'populate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

peak_gain(frequency)

Return the peak gain of the Gaussian antenna for a given frequency.

Return type:

float

class ephemerista.comms.antennas.MSIPattern(*, type='msi', filename, content)

The MSIPattern class.

This class provides the ability to import custom antenna pattern from other applications as MSI Planet files.

beamwidth(frequency)

Return the half-power beamwidth of the antenna pattern.

Return type:

float

property frequency: Frequency

the design frequency for which the pattern is valid.

Type:

Frequency

gain(frequency, angle)

Return the gain of the antenna pattern for a given frequency and elevation.

Notes

This method will throw an exception if the frequency of the MSI file and the given frequency are not within the same frequency band.

Return type:

float

model_config: ClassVar[ConfigDict] = {'alias_generator': <function to_camel>, 'populate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod read_file(file)

Read an MSI Planet file.

Return type:

Self

class ephemerista.comms.antennas.MSIPatternData(*, name, make=None, frequency, hWidth=None, vWidth=None, frontToBack=None, peakGain, gainUnit, tilt=None, comment=None, horizontal, vertical)

The MSIPatternData class.

This class models the data contained in an MSI Planet file.

model_config: ClassVar[ConfigDict] = {'alias_generator': <function to_camel>, 'populate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ephemerista.comms.antennas.PATTERN_DISCRIMINATOR = 'pattern_type'

When dividing by a quantity, if this quantity is lower than this threshold, an alternate formulation will be used to avoid division by zero

class ephemerista.comms.antennas.ParabolicPattern(*, type='parabolic', diameter, efficiency=0.65)

The ParabolicPattern class.

This class models the gain pattern of a parabolic antenna.

property area: float

area of the parabolic antenna.

Type:

float

beamwidth(frequency)

Return the half-power beamwidth of the antenna for a given frequency in radians.

Return type:

float

classmethod from_beamwidth(beamwidth, frequency)

Build an equivalent parabolic antenna from the given beamwidth and frequency.

Parameters:
  • beamwidth (float) – Half-power beamwidth in radians

  • frequency (Frequency) – Frequency

Return type:

Self

gain(frequency, angle)

Return the gain of the parabolic antenna for a given frequency and elevation.

Notes

Assumes an uniform illuminated aperture (i.e. taper parameter tau = 1.0)

References

Equation (17) of https://web.archive.org/web/20160101021857/https://library.nrao.edu/public/memos/alma/memo456.pdf.

Return type:

ndarray

model_config: ClassVar[ConfigDict] = {'alias_generator': <function to_camel>, 'populate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

peak_gain(frequency)

Return the peak gain of the parabolic antenna for a given frequency.

Return type:

float

class ephemerista.comms.antennas.Pattern

Abstract base class for gain patterns.

abstractmethod beamwidth(frequency)

Return the half-power beamwidth of the antenna for a given frequency in radians.

Return type:

float

abstractmethod gain(frequency, angle)

Return the gain of the antenna for a given frequency and elevation.

Return type:

float

model_config: ClassVar[ConfigDict] = {'alias_generator': <function to_camel>, 'populate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ephemerista.comms.antennas.SimpleAntenna(*, designFrequency=None, boresightVector=(0.0, 0.0, 1.0), type='simple', gainDb, beamwidthDeg)

The SimpleAntenna class.

This class provides a simplified antenna model that uses fixed gain and half-power beamwidth values.

beamwidth(frequency)

Return the half-power beamwidth of the antenna for a given frequency.

Return type:

float

gain(frequency, angle)

Return the gain of the antenna for a given frequency and elevation.

Return type:

float

model_config: ClassVar[ConfigDict] = {'alias_generator': <function to_camel>, 'populate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

exception ephemerista.comms.antennas.UndefinedBeamwidthError

Raise if the MSI Planet file did not provide a beamwidth.