Antennas - ephemerista.comms.antennas

The antennas.py module.

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

pydantic model ephemerista.comms.antennas.Antenna

Abstract base class for antenna models.

Fields:
field boresight_vector: TypeAliasType = (0.0, 0.0, 1.0) (alias 'boresightVector')

The boresight vector of the antenna in the local reference frame (LVLH when attached to a spacecraft, SEZ when attached to a ground station)

field design_frequency: float | None = None (alias 'designFrequency')

The design frequency of the antenna in Hz

Constraints:

  • gt = 0.0

abstractmethod beamwidth(frequency)

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

Return type:

float

abstractmethod gain(frequency, angle)

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

Return type:

float

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.

Return type:

Surface

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.

property boresight_array: ndarray

boresight vector.

Type:

numpy.ndarray

events
pydantic model ephemerista.comms.antennas.ComplexAntenna

The ComplexAntenna class.

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

Fields:
field antenna_type: Literal['complex'] = 'complex' (alias 'type')

Complex antenna type

field pattern: TypeAliasType [Required]

Pattern type discriminator

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

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.

Return type:

Map

References

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

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.

pydantic model ephemerista.comms.antennas.DipolePattern

The DipolePattern class.

This class models the gain pattern of a dipole antenna.

Fields:
field length: float [Required]

Antenna length in meters

Constraints:

  • gt = 0.0

field pattern_type: Literal['dipole'] = 'dipole' (alias 'patternType')

Dipole pattern type

beamwidth(frequency)

Return the beamwidth of the dipole pattern.

Return type:

float

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.

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.

Return type:

ndarray

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.

peak_gain(frequency)

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

Return type:

float

pydantic model ephemerista.comms.antennas.GaussianPattern

The GaussianPattern class.

This class models a Gaussian gain pattern.

Fields:
field diameter: float [Required]

Antenna diameter in meters

Constraints:

  • gt = 0.0

field efficiency: float [Required]

Antenna efficiency, between 0 and 1

Constraints:

  • gt = 0.0

  • le = 1.0

field pattern_type: Literal['gaussian'] = 'gaussian' (alias 'patternType')

Gaussian antenna pattern

beamwidth(frequency)

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

Return type:

float

References

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

gain(frequency, angle)

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

Return type:

ndarray

References

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

peak_gain(frequency)

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

Return type:

float

pydantic model ephemerista.comms.antennas.MSIPattern

The MSIPattern class.

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

Fields:
field content: str [Required]

Content of the MSI file

field filename: str [Required]

Name of the MSI file

field pattern_type: Literal['msi'] = 'msi' (alias 'patternType')
classmethod read_file(file)

Read an MSI Planet file.

Return type:

Self

beamwidth(frequency)

Return the half-power beamwidth of the antenna pattern.

Return type:

float

gain(frequency, angle)

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

Return type:

float

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.

property frequency

the design frequency for which the pattern is valid in Hz.

Type:

float

pydantic model ephemerista.comms.antennas.MSIPatternData

The MSIPatternData class.

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

Fields:
field comment: str | None = None
field frequency: float [Required]

Design frequency of the antenna in Hz

field front_to_back: float | None = None (alias 'frontToBack')

Front-to-back ratio in dB

field gain_unit: Literal['dBd', 'dBi'] [Required] (alias 'gainUnit')

Unit of the peak gain

field h_width: float | None = None (alias 'hWidth')

Horizontal 3 dB beamwidth

field horizontal: Annotated[Union[ndarray[tuple[int], dtype[float64]], Annotated[Path], MultiArrayNumpyFile]] [Required]
Constraints:

  • dimensions = 1

  • data_type = <class ‘numpy.float64’>

  • strict_data_typing = False

  • serialize_numpy_array_to_json = <function pd_np_native_numpy_array_to_data_dict_serializer at 0x7945b2f7e520>

  • json_schema_from_type_data = <function pd_np_native_numpy_array_json_schema_from_type_data at 0x7945b2f7e840>

  • __module__ = pydantic_numpy.helper.annotation

field make: str | None = None

Manufacturer of the antenna

field name: str [Required]

Name of the antenna

field peak_gain: float [Required] (alias 'peakGain')

Peak gain of the antenna in dBd or dBi

field tilt: float | None = None

Electrical tilt of the main beam in degrees

field v_width: float | None = None (alias 'vWidth')

Vertical 3 dB beamwidth

field vertical: Annotated[Union[ndarray[tuple[int], dtype[float64]], Annotated[Path], MultiArrayNumpyFile]] [Required]
Constraints:

  • dimensions = 1

  • data_type = <class ‘numpy.float64’>

  • strict_data_typing = False

  • serialize_numpy_array_to_json = <function pd_np_native_numpy_array_to_data_dict_serializer at 0x7945b2f7e520>

  • json_schema_from_type_data = <function pd_np_native_numpy_array_json_schema_from_type_data at 0x7945b2f7e840>

  • __module__ = pydantic_numpy.helper.annotation

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

pydantic model ephemerista.comms.antennas.ParabolicPattern

The ParabolicPattern class.

This class models the gain pattern of a parabolic antenna.

Fields:
field diameter: float [Required]

Antenna diameter in meters

Constraints:

  • gt = 0.0

field efficiency: float = 0.65

Antenna efficiency, between 0 and 1

Constraints:

  • gt = 0.0

  • le = 1.0

field pattern_type: Literal['parabolic'] = 'parabolic' (alias 'patternType')

Parabolic pattern type

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 (float) – Frequency in Hz

Return type:

Self

beamwidth(frequency)

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

Return type:

float

gain(frequency, angle)

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

Return type:

ndarray

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.

peak_gain(frequency)

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

Return type:

float

property area: float

area of the parabolic antenna.

Type:

float

pydantic model 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

events
pydantic model ephemerista.comms.antennas.SimpleAntenna

The SimpleAntenna class.

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

Fields:
field antenna_type: Literal['simple'] = 'simple' (alias 'type')

Simple antenna type

field beamwidth_deg: float [Required] (alias 'beamwidthDeg')

Beamwidth in degrees

Constraints:

  • ge = 0.0

field gain_db: float [Required] (alias 'gainDb')

Antenna gain in dBi

Constraints:

  • ge = 0.0

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

exception ephemerista.comms.antennas.UndefinedBeamwidthError

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