`GroundStation`#

class GroundStation(name: str, spice_id: int | str = None)#

Bases: Body

Represents a ground station for spacecraft communication modeling.

A ground station is a Body with no mass or SRP properties. Its primary role is to supply the observer position for radiometric observables (range, range-rate, Doppler).

Parameters:

name (str) – The name of the ground station.
spice_id (int or float, optional) – The SPICE ID of the ground station, defaults to None.

See also

scarabaeus.CelestialBody: Planetary body on whose surface a GroundStation is placed.

Attributes:

mass_profile: Stored constant or polynomial mass profile.
name: The name of the Body object.
spice_id: The SPICE ID of the Body object.

Methods

`elevation`(target, epoch[, frame, origin])	Computes the elevation angle of a spacecraft as seen from the ground station.
`fit_mass_profile_from_data`(t_array, m_array, ...)	Fits a polynomial to a mass time history and sets it as the new mass profile.
`get_mass`(t)	Evaluates the time-varying mass profile at specified epochs.
`get_state`(epoch_0[, reference_frame, origin])	Retrieves the state of the body relative to a given origin in a specified reference frame.
`mass`([t])	Returns the mass of the body.
`set_mass_profile`(poly, units)	Sets the mass profile of the body using a polynomial function and associated units.
`station_visibility`(target, epoch[, ...])	Determines if a spacecraft is visible to the ground station given an elevation mask for a single epoch or a sequence of epochs.

elevation(target: Spacecraft, epoch: EpochArray, frame: str = 'J2000', origin: str = 'EARTH') → float | ndarray#

Computes the elevation angle of a spacecraft as seen from the ground station.

Parameters:

target (Spacecraft) – The target spacecraft object. Its SPICE ID is used to query its state via SPICE.
epoch (EpochArray) – The epoch or sequence of epochs at which to evaluate elevation.
frame (str, optional) – Reference frame for position queries. Defaults to 'J2000'.
origin (str, optional) – Observer body for SPICE state queries. Defaults to 'SUN'.

Returns:

elevation – Elevation angle(s) in degrees above the horizon. Returns a scalar for a single epoch or an array for multiple epochs.

Return type:

float or numpy.ndarray

fit_mass_profile_from_data(t_array: ndarray, m_array: ndarray, domain: tuple, units: Units) → None#

Fits a polynomial to a mass time history and sets it as the new mass profile.

Parameters:

t_array (numpy.ndarray) – Time values in seconds (ephemeris time).
m_array (numpy.ndarray) – Corresponding mass values.
deg (int) – Degree of the polynomial.
domain (tuple) – Domain [t0, tf] for the polynomial conversion.
units (ArrayWUnits) – Units to assign to the mass profile. If None, uses existing mass profile units.

Return type:

None

get_mass(t: EpochArray) → ArrayWUnits#

Evaluates the time-varying mass profile at specified epochs.

Parameters:: t (EpochArray) – Time(s) in ephemeris seconds (TDB).
Returns:: mass – Evaluated mass at each input epoch.
Return type:: ArrayWUnits

get_state(epoch_0, reference_frame: str = 'J2000', origin: str = 'EARTH') → ArrayWFrame#

Retrieves the state of the body relative to a given origin in a specified reference frame.

Parameters:

epoch_0 (EpochArray) – The epoch times for which the state is to be computed.
reference_frame (str) – The reference frame in which the state is desired. Defaults to ‘J2000’.
origin (str) – The origin body relative to which the state is computed. Defaults to 'EARTH'.

Returns:

state_vector – The state vector of the body relative to the origin.

Return type:

ArrayWFrame

mass(t: EpochArray | float | ndarray = None) → ArrayWUnits#

Returns the mass of the body. If the mass is time-varying, evaluates it at time t. If the mass is constant, returns the same value regardless of t.

Parameters:: t (EpochArray, float, or np.ndarray, optional) – Time(s) in ephemeris seconds (TDB) at which to evaluate the mass. Or None for constant mass.
Returns:: Mass at time t or constant mass.
Return type:: ArrayWUnits

set_mass_profile(poly: SCBPolynomial, units: Units) → None#

Sets the mass profile of the body using a polynomial function and associated units.

Parameters:

poly (SCBPolynomial) – A polynomial object representing the mass profile.
units (Units) – The units associated with the mass profile.

Return type:

None

station_visibility(target: Spacecraft, epoch: EpochArray, elevation_mask: float = 10.0, return_angles: bool = False, frame: str = 'J2000', origin: str = 'EARTH')#

Determines if a spacecraft is visible to the ground station given an elevation mask for a single epoch or a sequence of epochs.

Positions are retrieved via SPICE using the SPICE names/IDs of this ground station and the target spacecraft, then the elevation (and optionally azimuth) are computed in the requested reference frame.

The station elevation angle \(\varepsilon\) above the local horizon is computed from

\[\varepsilon = 90^\circ - \theta_{nadir}, \qquad \cos\theta_{nadir} = \frac{(\mathbf{r}_{sc} - \mathbf{r}_{gs})\cdot\mathbf{r}_{gs}} {\|\mathbf{r}_{sc} - \mathbf{r}_{gs}\|\,\|\mathbf{r}_{gs}\|}\]

The station is visible when \(\varepsilon \geq \varepsilon_{mask}\) (default 10°).

Parameters:

target (Spacecraft) – The target spacecraft. Its SPICE ID is used to query its state via SPICE.
epoch (EpochArray) – The epoch or sequence of epochs at which to evaluate visibility.
elevation_mask (float, optional) – Minimum elevation angle in degrees above the horizon for the spacecraft to be considered visible. Defaults to 10.0.
return_angles (bool, optional) – If True, also returns the elevation and azimuth angles. Defaults to False.
frame (str, optional) – Reference frame for position queries. Defaults to 'J2000'.
origin (str, optional) – Observer body for SPICE state queries. Defaults to 'SUN'.

Returns:

visible (bool or np.ndarray of bool) – True if the spacecraft is above the elevation mask as seen from this ground station. Returns a scalar for a single epoch or an array for multiple epochs.
elevation (float or np.ndarray of float) – Elevation angle(s) in degrees above the horizon. Only returned if return_angles = True.
azimuth (float or np.ndarray of float) – Azimuth angle(s) in degrees measured clockwise from North. Only returned if return_angles = True.

property mass_profile: ArrayWUnits | SCBPolynomial#: Stored constant or polynomial mass profile.

property name: str#: The name of the Body object.

property spice_id: int | str#: The SPICE ID of the Body object.

GroundStation#

`GroundStation`#