GroundStation#

class GroundStation(name: str, spice_id: int | str = None, *, central_body='EARTH', body_fixed_frame='ITRF93', body_fixed_position=None, body_fixed_velocity=None, position_epoch=None, surface_displacement=None, barycentric_transformation=False, body_orientation=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:
namestr

The name of the ground station.

spice_idint or float, optional

The SPICE ID of the ground station, defaults to None.

central_bodystr or Body, optional

Body supporting the station, default EARTH. The supplied coordinates or station kernels express its position relative to this center.

body_fixed_frameFrame or str, optional

Body-fixed SPICE frame. For another planet supply its frame, e.g. IAU_MARS, together with central_body="MARS". Defaults to 'ITRF93'.

body_fixed_positionArrayWUnits or array_like, optional

Fixed Cartesian station coordinates relative to central_body in body_fixed_frame. Bare values are km. When supplied, no station SPK is needed; otherwise the station position comes from loaded kernels. Use from_cylindrical() for a longitude/radius/Z table.

body_fixed_velocityArrayWUnits or array_like, optional

Constant body-fixed velocity of explicit coordinates, plate motion. Bare values are km/s. Requires position_epoch.

position_epochEpochArray or float, optional

Single epoch at which body_fixed_position holds; a float is TDB seconds past J2000. Defaults to None.

surface_displacementobject or list of objects, optional

Time-varying station displacement, e.g. SolidTide, PoleTide, OceanLoading, or a list of them, summed. See surface_displacement.

barycentric_transformationbool, optional

Apply the geocentric-to-barycentric transformation to space-fixed states, default false. See barycentric_transformation.

body_orientationBodyOrientation, optional

Small orientation correction to the loaded body-fixed frame, from earth_correction(). Absolute EOPs are loaded as a PCK instead. See body_orientation.

Attributes:
barycentric_transformation

Whether space-fixed states carry the geocentric-to-barycentric transformation.

body_fixed_frame

Body-fixed SPICE frame name of this station, e.g.

body_fixed_position

Explicit Cartesian coordinates in km, or None for a kernel station.

body_fixed_velocity

Constant body-fixed velocity of explicit coordinates in km/s, or None.

body_orientation

Optional BodyOrientation station correction.

earth_orientation

Earth orientation correction applied to this station, or None.

mass_profile

Stored constant or polynomial mass profile.

name

The name of the Body object.

position_epoch

TDB seconds past J2000 at which body_fixed_position holds, or None.

spice_id

The SPICE ID of the Body object.

surface_displacement

Optional time-varying displacement of this station in its body-fixed frame.

tide_reference

The attached tide whose Love and Shida numbers an estimate refers to.

Methods

cylindrical_basis(epoch[, frame])

Return the local cylindrical basis and its time derivative.

displacement_state(epoch[, frame])

Return the total attached surface displacement of this station.

elevation(target, epoch[, frame, origin])

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

eop_displacement(epoch[, frame, as_state])

This station's displacement from its Earth orientation correction.

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.

from_cylindrical(name[, spice_id, ...])

Define a fixed station from absolute cylindrical table coordinates.

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.

iau_pole_correction(epoch[, frame])

State correction from an estimated IAU pole and prime meridian.

iau_pole_partials(epoch[, frame])

Sensitivity of this station's state to the estimated IAU pole.

inertial_rotation_partials(epoch[, frame])

Sensitivity of this station's state to a J2000 rotation vector.

location_partials(epoch[, frame, ...])

Sensitivity of this station's state to its body-fixed location delta.

mass([t])

Returns the mass of the body.

nominal_state(epoch[, frame])

Return this station's uncorrected state relative to its central body.

pole_tide_partials(epoch[, frame])

Sensitivity of this station's state to the pole the pole tide uses.

reset_mass_history()

Restore the mass the body was built with and forget fitted profiles.

rotation_partials(epoch[, frame, location, ...])

Sensitivity of this station's state to a body-fixed rotation vector.

set_mass_profile(poly, units)

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

state_correction(epoch[, frame, location, ...])

Transform station location and orientation corrections into a state delta.

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.

tide_correction(epoch[, frame, love_h2, ...])

Move the attached tide from its own Love numbers to estimated ones.

tide_partials(epoch[, frame])

Sensitivity of this station's state to the Love and Shida numbers.

See also

scarabaeus.CelestialBody

Planetary body on whose surface a GroundStation is placed.

classmethod from_cylindrical(name, spice_id=None, *, longitude, cylindrical_radius, z, central_body='EARTH', body_fixed_frame='ITRF93', **kwargs)#

Define a fixed station from absolute cylindrical table coordinates.

Parameters:
namestr

Station name.

spice_idint or str, optional

NAIF identifier; required for a name unknown to SPICE. Defaults to None, resolved from name.

longitudeArrayWUnits or float

East-positive longitude. Bare values are radians; unit-bearing values may use degrees. This is an angle, not an east arc length.

cylindrical_radius, zArrayWUnits or float

Distance from the spin axis and signed height along that axis. Bare values are km. These are absolute coordinates, not estimates or corrections to a station kernel.

central_bodystr or Body, optional

Supporting body, default EARTH.

body_fixed_framestr, optional

Frame of the supplied table, default ITRF93.

**kwargs

Passed to the constructor, e.g. body_fixed_velocity, position_epoch, surface_displacement, barycentric_transformation or body_orientation.

Returns:
GroundStation

Station with Cartesian coordinates \((\rho\cos\lambda,\rho\sin\lambda,Z)\) and zero velocity in the supplied frame. Frame rotation supplies its inertial velocity.

Raises:
ValueError

For non-scalar/non-finite inputs or a negative cylindrical radius.

cylindrical_basis(epoch, frame=None) → tuple#

Return the local cylindrical basis and its time derivative.

Parameters:
epochEpochArray or float

Single epoch within the required kernel coverage; a float is TDB seconds past J2000.

frameFrame or str, optional

Body-fixed axes. Defaults to body_fixed_frame.

Returns:
basisnumpy.ndarray

(3,3) unitless matrix mapping (radial, east, Z) lengths into Cartesian body-fixed coordinates, like any direction cosine matrix.

derivativeArrayWUnits

Its (3,3) rate, per second.

Raises:
ValueError

At the spin axis, where nominal longitude is undefined.

Notes

The basis is evaluated at the actual epoch using the station’s own central body. East is an arc length, \(\rho\,\Delta\lambda\), not a longitude angle. Body-fixed station motion gives \(\dot\lambda=(x\dot y-y\dot x)/(x^2+y^2)\); its contribution to the inertial velocity must be retained when estimating Doppler.

displacement_state(epoch, frame=None) → ArrayWFrame#

Return the total attached surface displacement of this station.

Parameters:
epochEpochArray or float

Single epoch; a float is TDB seconds past J2000.

frameFrame or str, optional

Output axes. Defaults to body_fixed_frame.

Returns:
ArrayWFrame

Sum of every attached surface_displacement and its rate, in km and km/s in frame, shape (6,); zeros when none is attached.

Notes

This is the term nominal_state() adds to the coordinates or the station SPK. Models that read the station from the kernel directly rather than through nominal_state() add it themselves, so every model places the station at the same displaced point.

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:
targetSpacecraft

The target spacecraft object. Its SPICE ID is used to query its state via SPICE.

epochEpochArray

The epoch or sequence of epochs at which to evaluate elevation.

framestr, optional

Reference frame for position queries. Defaults to 'J2000'.

originstr, optional

Observer body for SPICE state queries. Defaults to 'EARTH'.

Returns:
elevationfloat or numpy.ndarray

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

eop_displacement(epoch, frame='J2000', as_state: bool = False)#

This station’s displacement from its Earth orientation correction.

Parameters:
epochEpochArray or float

Single epoch; a float is TDB seconds past J2000.

frameFrame or str, optional

Frame to express the displacement in. Defaults to 'J2000'.

as_statebool, optional

Return position and velocity rather than position alone. The velocity term matters for Doppler — see state_displacement(). Defaults to False.

Returns:
ArrayWFrame or None

Displacement in km (and km/s when as_state) in frame, shape (3,) or (6,), or None when no correction is attached.

Notes

The station’s body-fixed position comes from its explicit coordinates or the loaded station kernels, relative to central_body, so this is a first-order rigid rotation of that nominal position — see BodyOrientation.

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_arraynumpy.ndarray

Time values in seconds (ephemeris time).

m_arraynumpy.ndarray

Corresponding mass values.

degint

Degree of the polynomial.

domaintuple

Domain [t0, tf] for the polynomial conversion.

unitsArrayWUnits

Units to assign to the mass profile. If None, uses existing mass profile units.

Returns:
None
get_mass(t: EpochArray) → ArrayWUnits#

Evaluates the time-varying mass profile at specified epochs.

Parameters:
tEpochArray

Time(s) in ephemeris seconds (TDB).

Returns:
massArrayWUnits

Evaluated mass at each input epoch.

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_0EpochArray

The epoch times for which the state is to be computed.

reference_framestr

The reference frame in which the state is desired. Defaults to ‘J2000’.

originstr

The origin body relative to which the state is computed. Defaults to 'EARTH'.

Returns:
state_vectorArrayWFrame

The state vector of the body relative to the origin.

iau_pole_correction(epoch, frame='J2000', **pole) → ArrayWFrame#

State correction from an estimated IAU pole and prime meridian.

Parameters:
epochEpochArray or float

Single epoch; a float is TDB seconds past J2000.

frameFrame or str, optional

Output axes. Defaults to 'J2000'.

**poleArrayWUnits or float

Estimated pole_ra, pole_dec, pole_w0 and pole_pm of the central body, as iau_angles() takes them. Bare numbers are radians and, for pole_pm, deg/day.

Returns:
ArrayWFrame

Six components in km and km/s in frame, to add to nominal_state().

Raises:
MissingPoleCoefficientsError

From iau_angles(), raised by iau_pole_coefficients() reading no secular constants for the central body.

Notes

The estimate is applied as a perturbation of the station’s own frame: with \(R_e\) and \(R_s\) the body-fixed to J2000 rotations of iau_angles() with and without the estimated values, the station moves to \(r' = P r\) with \(P = R_e R_s^T\), and

\[v' = \dot P r + P v, \qquad \dot P = [\omega_e \times] P - P [\omega_s \times],\]

where \(r, v\) are nominal_state() in J2000 and \(\omega\) the body’s angular velocity. \(P\) is exact, not linearized, and is the identity whenever the estimate equals the secular model; for a body whose PCK frame has no nutation terms (Mars in pck00010) the station then turns with exactly the orientation that SphericalHarmonicsGravity and the optical models apply for the same state. An estimated pole_ra or pole_dec is constant and pole_pm drops the quadratic term, as there, so an estimate held at the PCK constant term drifts from the secular model by the dropped rate over the years since J2000.

The perturbation acts on nominal_state(), not on the estimated location or body-fixed corrections; those cross terms are products of two corrections.

iau_pole_partials(epoch, frame='J2000', **pole) → ArrayWUnits#

Sensitivity of this station’s state to the estimated IAU pole.

Parameters:
epochEpochArray or float

Single epoch; a float is TDB seconds past J2000.

frameFrame or str, optional

Output axes. Defaults to 'J2000'.

**poleArrayWUnits or float

Values to linearize about, as in iau_pole_correction(); a missing one is linearized about its secular term.

Returns:
ArrayWUnits

(6, 4) Jacobian of iau_pole_correction() in frame axes, columns pole_ra, pole_dec, pole_pm, pole_w0 (the order of BodyOrientation.IAU_POLE_PARAMETERS), in km and km/s per radian (ROTATION_PARTIAL_UNITS) and, for pole_pm, per deg/day (POLE_PM_PARTIAL_UNITS).

Raises:
MissingPoleCoefficientsError

As in iau_pole_correction().

Notes

Each angle turns the estimated orientation about one J2000 axis \(e\) of _iau_axes(), so with \(g\) the derivative of the angle with respect to the parameter (1, or \(d\,\pi/180\) for pole_pm with \(d\) days past J2000),

\[\frac{\partial r'}{\partial q} = g\, e \times r', \qquad \frac{\partial v'}{\partial q} = \dot g\, e \times r' + g\,(\dot e \times r' + e \times v'),\]

where \(\dot e\) follows the estimated orientation: \(\dot{\hat z} = 0\), \(-\dot{\hat n} = \dot\alpha_e (\cos\alpha_e, \sin\alpha_e, 0)\) and \(\dot{\hat p} = \omega_e \times \hat p\).

inertial_rotation_partials(epoch, frame='J2000') → ArrayWUnits#

Sensitivity of this station’s state to a J2000 rotation vector.

Parameters:
epochEpochArray or float

Single epoch; a float is TDB seconds past J2000.

frameFrame or str, optional

Output axes. Defaults to 'J2000'.

Returns:
ArrayWUnits

(6, 3) Jacobian in km and km/s per radian (ROTATION_PARTIAL_UNITS), in frame axes. The correction is linear in the rotation, so the Jacobian times the rotation vector is also the state correction itself.

Notes

A small rotation \(\omega\) held fixed in inertial space moves the station by \(\omega \times r_I\) and its inertial velocity by \(\omega \times v_I\), so the derivative is \(-[r_I\times]\) and \(-[v_I\times]\). This differs from rotation_partials(), whose rotation is held fixed in the body and so turns with it. A celestial-pole offset is of this inertial kind.

The rotation acts on nominal_state(), not on the estimated location or body-fixed corrections; those cross terms are products of two small corrections.

location_partials(epoch, frame='J2000', *, cylindrical: bool = False, location_frame=None, rotation_vector=None) → ArrayWUnits#

Sensitivity of this station’s state to its body-fixed location delta.

Parameters:
epochEpochArray or float

Single epoch; a float is TDB seconds past J2000.

frameFrame or str, optional

Output axes. Defaults to 'J2000'.

cylindricalbool, optional

Differentiate with respect to (radius, east arc length, Z) rather than Cartesian components. Defaults to False.

location_frameFrame or str, optional

Axes the delta is declared in. Defaults to body_fixed_frame.

rotation_vectorArrayWUnits or array_like, shape (3,), optional

Estimated body-fixed rotation, added to any attached body_orientation for the location/orientation cross term. Bare numbers are radians. Defaults to None, meaning zero.

Returns:
ArrayWUnits

(6, 3) Jacobian in km and km/s per km (LOCATION_PARTIAL_UNITS), in frame axes, matching the differentiated state_correction() exactly rather than approximating it.

Raises:
ValueError

For undefined cylindrical longitude, or an attached orientation expressed in a different body-fixed frame.

Notes

The cylindrical basis rotates with the body, so its time derivative contributes a velocity row: a station’s east coordinate is not static in inertial space. Omitting it biases any Doppler partial.

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:
tEpochArray, float, or np.ndarray, optional

Time(s) in ephemeris seconds (TDB) at which to evaluate the mass. Or None for constant mass.

Returns:
ArrayWUnits

Mass at time t or constant mass.

nominal_state(epoch, frame=None) → ArrayWFrame#

Return this station’s uncorrected state relative to its central body.

Parameters:
epochEpochArray or float

Single epoch; a float is TDB seconds past J2000.

frameFrame or str, optional

Output SPICE frame. Defaults to body_fixed_frame.

Returns:
ArrayWFrame

Six components in km and km/s in frame, from the explicit coordinates (moved by any body_fixed_velocity) or loaded station SPK, plus any attached surface_displacement. Orientation still comes from SPICE frames. This deliberately bypasses estimated corrections so they are applied exactly once by state_correction(); a tidal displacement is not estimated, it is where the station actually is, so estimated corrections are linearised about the displaced point. Any frame but the body-fixed one also carries the barycentric_transformation when that is enabled.

Raises:
MissingPositionEpochError

If body_fixed_velocity is set but position_epoch is not.

VelocityWithoutPositionError

If body_fixed_velocity is set on a kernel station.

pole_tide_partials(epoch, frame='J2000') → ArrayWUnits#

Sensitivity of this station’s state to the pole the pole tide uses.

Parameters:
epochEpochArray or float

Single epoch; a float is TDB seconds past J2000.

frameFrame or str, optional

Output axes. Defaults to 'J2000'.

Returns:
ArrayWUnits

(6, 2) Jacobian in km and km/s per radian of pole x and y (ROTATION_PARTIAL_UNITS), in frame axes, or zeros when no model with state_displacement_pole_partials, such as a PoleTide, is attached.

Notes

An estimated eop_delta_pole_x/eop_delta_pole_y turns the station through rotation_partials() and also moves the pole the pole tide responds to. The tide is linear in the pole, so this Jacobian times the pole delta is the exact change, taken about the undisplaced position like tide_partials().

reset_mass_history() → None#

Restore the mass the body was built with and forget fitted profiles.

Every propagated leg appends the profile it fitted, and the next leg starts from the last one. Propagating the same mission again (a filter re-linearizing its reference, say) would otherwise start the first leg from the mass the previous run ended with, and get_mass() would return profiles from earlier runs that cover the same epochs.

The profile lists are cleared in place: force-model copies of this body share them by reference.

Returns:
None
rotation_partials(epoch, frame='J2000', *, location=None, location_frame=None, cylindrical: bool = False) → ArrayWUnits#

Sensitivity of this station’s state to a body-fixed rotation vector.

Parameters:
epochEpochArray or float

Single epoch; a float is TDB seconds past J2000.

frameFrame or str, optional

Output axes. Defaults to 'J2000'.

locationArrayWFrame, ArrayWUnits or array_like, shape (3,), optional

Current estimated location delta, so the derivative is taken about the same displaced point state_correction() rotates. Bare numbers are km. Defaults to None, meaning zero.

location_frameFrame or str, optional

Axes of location. Defaults to the frame of an ArrayWFrame location, else body_fixed_frame.

cylindricalbool, optional

Interpret location as (radius, east, Z). Defaults to False.

Returns:
ArrayWUnits

(6, 3) Jacobian in km and km/s per radian (ROTATION_PARTIAL_UNITS), in frame axes.

Raises:
ValueError

For undefined cylindrical longitude, or an attached orientation expressed in a different body-fixed frame.

Notes

A small active rotation moves the station by \(\varepsilon \times r\), so the derivative is \(-[r\times]\) — evaluated on both the position and the body-fixed velocity, since a rotated station also sits on a different radius from the spin axis. This is the block every Earth-orientation parameter chains through.

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

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

Parameters:
polySCBPolynomial

A polynomial object representing the mass profile.

unitsUnits

The units associated with the mass profile.

Returns:
None
state_correction(epoch, frame='J2000', *, location=None, location_frame=None, cylindrical: bool = False, rotation_vector=None) → ArrayWFrame#

Transform station location and orientation corrections into a state delta.

Parameters:
epochEpochArray or float

Single epoch; a float is TDB seconds past J2000.

frameFrame or str, optional

Output axes. Defaults to 'J2000'.

locationArrayWFrame, ArrayWUnits or array_like, shape (3,), optional

Estimated body-fixed coordinate delta. Bare numbers are km. Defaults to None, meaning zero.

location_frameFrame or str, optional

Axes of location. Defaults to the frame of an ArrayWFrame location, else body_fixed_frame.

cylindricalbool, optional

If true, interpret location as (delta radius, east arc length, delta Z). Otherwise it is Cartesian. Defaults to False.

rotation_vectorArrayWUnits or array_like, shape (3,), optional

Estimated active body-fixed X/Y/Z rotation, added to the attached body_orientation, if present. Bare numbers are radians. Defaults to None, meaning zero.

Returns:
ArrayWFrame

Position/velocity displacement in km and km/s in frame, shape (6,).

Raises:
ValueError

For non-finite corrections, undefined cylindrical longitude, or an attached orientation expressed in a different body-fixed frame.

Notes

Location is applied before the first-order rigid rotation, retaining the location/orientation cross term. The full sxform carries both the rotated displacement and its velocity. This method uses nominal kernels directly and does not change their frame definitions.

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:
targetSpacecraft

The target spacecraft. Its SPICE ID is used to query its state via SPICE.

epochEpochArray

The epoch or sequence of epochs at which to evaluate visibility.

elevation_maskfloat, optional

Minimum elevation angle in degrees above the horizon for the spacecraft to be considered visible. Defaults to 10.0.

return_anglesbool, optional

If True, also returns the elevation and azimuth angles. Defaults to False.

framestr, optional

Reference frame for position queries. Defaults to 'J2000'.

originstr, optional

Observer body for SPICE state queries. Defaults to 'EARTH'.

Returns:
visiblebool 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.

elevationfloat or np.ndarray of float

Elevation angle(s) in degrees above the horizon. Only returned if return_angles = True.

azimuthfloat or np.ndarray of float

Azimuth angle(s) in degrees measured clockwise from North. Only returned if return_angles = True.

tide_correction(epoch, frame='J2000', *, love_h2=None, shida_l2=None) → ArrayWFrame#

Move the attached tide from its own Love numbers to estimated ones.

Parameters:
epochEpochArray or float

Single epoch; a float is TDB seconds past J2000.

frameFrame or str, optional

Output axes. Defaults to 'J2000'.

love_h2, shida_l2float, optional

Estimated \(h_2\) and \(l_2\), read as the numbers of tide_reference. Defaults to None, meaning each attached model keeps its own number.

Returns:
ArrayWFrame

State delta in km and km/s in frame, shape (6,); zeros when no tide model with Love-number partials is attached.

Notes

nominal_state() already carries each tide model at its own \(h_2\) and \(l_2\), so only the difference is added here. Every attached model shifts by the same difference, the estimate minus the tide_reference number: a solid tide and a pole tide keep their different nominal numbers and move together, so tide_partials() is their sum. The degree-2 displacement is linear in both numbers, which makes that sum times the difference exact for the closed-form models and first order for the IERS 2010 routine.

tide_partials(epoch, frame='J2000') → ArrayWUnits#

Sensitivity of this station’s state to the Love and Shida numbers.

Parameters:
epochEpochArray or float

Single epoch; a float is TDB seconds past J2000.

frameFrame or str, optional

Output axes. Defaults to 'J2000'.

Returns:
ArrayWUnits

(6, 2) Jacobian in km and km/s (STATE_UNITS) per unit \(h_2\) or \(l_2\), in frame axes, or zeros when no surface_displacement is attached.

Notes

The tidal response is what these numbers scale, so a station with no tide model attached has no sensitivity to them – estimating them then gives a zero column, which a filter will not like. The Jacobian is taken about the undisplaced position, which is where the tide model itself evaluates. It sums every attached model, since tide_correction() shifts all of them by the same amount.

LOCATION_PARTIAL_UNITS = (unitless, unitless, unitless, Hz, Hz, Hz)#

Row units of location_partials(), per km of location delta.

POLE_PM_PARTIAL_UNITS = ([(1.00E+03 m^1) (8.64E+04 sec^1) (1.75E-02 rad^-1)], [(1.00E+03 m^1) (8.64E+04 sec^1) (1.75E-02 rad^-1)], [(1.00E+03 m^1) (8.64E+04 sec^1) (1.75E-02 rad^-1)], [(8.64E+07 m^1) (1.75E-02 rad^-1)], [(8.64E+07 m^1) (1.75E-02 rad^-1)], [(8.64E+07 m^1) (1.75E-02 rad^-1)])#

Row units of the pole_pm column of iau_pole_partials(), per deg/day. The velocity rows are (km/s)/(deg/day): time cancels there, and Units keeps no scale for a cancelled dimension, so the day-to-second factor is carried by the length scale.

ROTATION_PARTIAL_UNITS = (km/rad, km/rad, km/rad, km/(sec*rad), km/(sec*rad), km/(sec*rad))#

Row units of a state Jacobian per radian of rotation or pole angle.

STATE_UNITS = (km, km, km, km/sec, km/sec, km/sec)#

Row units of a station state or state delta, and of its Jacobian with respect to a unitless parameter such as a Love number.

property barycentric_transformation: bool#

Whether space-fixed states carry the geocentric-to-barycentric transformation.

Station coordinates are geocentric and in terrestrial units; a spacecraft trajectory and the planetary ephemerides are barycentric, in TDB units. Combining them consistently takes the Lorentz transformation of the station’s geocentric space-fixed position into the solar-system barycentric frame (Moyer, Formulation for Observed and Computed Values of Deep Space Network Data Types for Navigation, 2000, eq. 4-10):

\[\mathbf r_B = \left(1 - \tilde L - \frac{\gamma U}{c^2}\right)\mathbf r - \frac{(\mathbf V \cdot \mathbf r)\,\mathbf V}{2c^2}\]

with \(U\) the Sun’s potential at the central body, \(\mathbf V\) the central body’s barycentric velocity, and \(\tilde L\), \(\gamma\) from constants. The scale term is 2.5e-8, about 16 cm at the Earth’s surface, and the velocity term up to 3 cm on a daily cycle. JPL’s navigation software reports station states this way.

When true, nominal_state() applies it to output in any axes but the station’s body-fixed frame, whose output is unchanged; being a scale and a dot product, it is the same in any axes. Only the position is transformed. The velocity term would be 0.01 mm/s, and the light-time observables’ own station transformation (Measurement._compute_GS_in_SSB_space_time_RLT) is likewise applied to position alone. Defaults to false.

Raises:
TypeError

If set to anything other than a bool.

property body_fixed_frame: str#

Body-fixed SPICE frame name of this station, e.g. ITRF93 or IAU_MARS.

Station coordinates, surface displacements and estimated location and orientation corrections are all expressed in these axes. Assign a Frame or a frame name; the name is stored.

property body_fixed_position#

Explicit Cartesian coordinates in km, or None for a kernel station.

Returns a copy. Assign three finite lengths (ArrayWUnits or km values) to select a fixed table position; assign None to use the station SPK. No station kernel is written, loaded, or modified by this setting.

property body_fixed_velocity#

Constant body-fixed velocity of explicit coordinates in km/s, or None.

Plate motion. Published station coordinates hold at an epoch, position_epoch, and move from there at a published rate: the station is at body_fixed_position + body_fixed_velocity * (t - position_epoch) at every epoch t, with this velocity as its body-fixed rate. Returns a copy. Assign three finite speeds (ArrayWUnits or km/s values), or None for a station that does not move.

property body_orientation#

Optional BodyOrientation station correction.

earth_orientation remains an alias. This is a correction to the loaded nominal frame, not an absolute EOP model or a force-model change.

property earth_orientation#

Earth orientation correction applied to this station, or None.

A body-fixed frame from a binary PCK already carries that kernel’s polar motion and UT1. Setting an BodyOrientation here applies the difference between the kernels’ values and the ones an analysis pins, so the station’s inertial position matches the intended Earth orientation.

See also

scarabaeus.BodyOrientation.earth_correction

Construct an Earth EOP correction.

property mass_profile: ArrayWUnits | SCBPolynomial#

Stored constant or polynomial mass profile.

property name: str#

The name of the Body object.

property position_epoch#

TDB seconds past J2000 at which body_fixed_position holds, or None.

Needed once body_fixed_velocity is set. There is no default: a coordinate table names its epoch, and a wrong one moves the station by its velocity times the error. Assign a single EpochArray, in any time system, or TDB seconds; a non-finite epoch raises InvalidEpochError.

property spice_id: int | str#

The SPICE ID of the Body object.

property surface_displacement#

Optional time-varying displacement of this station in its body-fixed frame.

Set a SolidTide to move the station with the solid tide. Unlike body_orientation, this is not a correction to a nominal that might instead have been right: the station really is somewhere else at this epoch, so the displacement enters nominal_state() and every estimated parameter is linearised about the displaced point.

Any object exposing state_displacement(position, epoch, frame) and returning six components, as an ArrayWUnits or bare km and km/s, works, such as PoleTide and OceanLoading. The position it receives is bare km. A list or tuple of such models is summed, each evaluated at the undisplaced position. The property returns whatever was set.

property tide_reference#

The attached tide whose Love and Shida numbers an estimate refers to.

Returns:
object or None

The first surface_displacement model with state_displacement_partials, or None when none is attached.

Notes

A SolidTide and a PoleTide carry different nominal \(h_2\) and \(l_2\). One estimated number is read as this model’s, and every attached tide shifts by the estimate minus this model’s number (tide_correction()). Leaving the estimate at this model’s number therefore leaves every tide where it was.

exception InvalidEpochError#

Bases: ValueError

A position_epoch was not finite.

exception MissingPositionEpochError#

Bases: Exception

A station was given a body_fixed_velocity but no position_epoch to move it from.

exception VelocityWithoutPositionError#

Bases: Exception

A body_fixed_velocity was set on a station whose position comes from a station kernel, which carries its own motion.