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 radiansfrequency (
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.