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:
BodyRepresents a ground station for spacecraft communication modeling.
A ground station is a
Bodywith 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_bodyinbody_fixed_frame. Bare values are km. When supplied, no station SPK is needed; otherwise the station position comes from loaded kernels. Usefrom_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_positionholds; a float is TDB seconds past J2000. Defaults toNone.- surface_displacementobject or list of objects, optional
Time-varying station displacement, e.g.
SolidTide,PoleTide,OceanLoading, or a list of them, summed. Seesurface_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. Seebody_orientation.
- Attributes:
barycentric_transformationWhether space-fixed states carry the geocentric-to-barycentric transformation.
body_fixed_frameBody-fixed SPICE frame name of this station, e.g.
body_fixed_positionExplicit Cartesian coordinates in km, or None for a kernel station.
body_fixed_velocityConstant body-fixed velocity of explicit coordinates in km/s, or None.
body_orientationOptional
BodyOrientationstation correction.earth_orientationEarth orientation correction applied to this station, or
None.mass_profileStored constant or polynomial mass profile.
nameThe name of the Body object.
position_epochTDB seconds past J2000 at which
body_fixed_positionholds, or None.spice_idThe SPICE ID of the Body object.
surface_displacementOptional time-varying displacement of this station in its body-fixed frame.
tide_referenceThe 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.
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.CelestialBodyPlanetary 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 fromname.- 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_transformationorbody_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_displacementand its rate, in km and km/s inframe, 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 throughnominal_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 toFalse.
- Returns:
- ArrayWFrame or None
Displacement in km (and km/s when
as_state) inframe, shape (3,) or (6,), orNonewhen 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 — seeBodyOrientation.
- 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_w0andpole_pmof the central body, asiau_angles()takes them. Bare numbers are radians and, forpole_pm, deg/day.
- Returns:
- ArrayWFrame
Six components in km and km/s in
frame, to add tonominal_state().
- Raises:
- MissingPoleCoefficientsError
From
iau_angles(), raised byiau_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 inpck00010) the station then turns with exactly the orientation thatSphericalHarmonicsGravityand the optical models apply for the same state. An estimatedpole_raorpole_decis constant andpole_pmdrops 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 ofiau_pole_correction()inframeaxes, columnspole_ra,pole_dec,pole_pm,pole_w0(the order ofBodyOrientation.IAU_POLE_PARAMETERS), in km and km/s per radian (ROTATION_PARTIAL_UNITS) and, forpole_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\) forpole_pmwith \(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), inframeaxes. 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_orientationfor the location/orientation cross term. Bare numbers are radians. Defaults toNone, meaning zero.
- Returns:
- ArrayWUnits
(6, 3)Jacobian in km and km/s per km (LOCATION_PARTIAL_UNITS), inframeaxes, matching the differentiatedstate_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 anybody_fixed_velocity) or loaded station SPK, plus any attachedsurface_displacement. Orientation still comes from SPICE frames. This deliberately bypasses estimated corrections so they are applied exactly once bystate_correction(); a tidal displacement is not estimated, it is where the station actually is, so estimated corrections are linearised about the displaced point. Anyframebut the body-fixed one also carries thebarycentric_transformationwhen that is enabled.
- Raises:
- MissingPositionEpochError
If
body_fixed_velocityis set butposition_epochis not.- VelocityWithoutPositionError
If
body_fixed_velocityis 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), inframeaxes, or zeros when no model withstate_displacement_pole_partials, such as aPoleTide, is attached.
Notes
An estimated
eop_delta_pole_x/eop_delta_pole_yturns the station throughrotation_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 liketide_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 toNone, meaning zero.- location_frameFrame or str, optional
Axes of
location. Defaults to the frame of an ArrayWFramelocation, elsebody_fixed_frame.- cylindricalbool, optional
Interpret
locationas (radius, east, Z). Defaults toFalse.
- Returns:
- ArrayWUnits
(6, 3)Jacobian in km and km/s per radian (ROTATION_PARTIAL_UNITS), inframeaxes.
- 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 ArrayWFramelocation, elsebody_fixed_frame.- cylindricalbool, optional
If true, interpret
locationas (delta radius, east arc length, delta Z). Otherwise it is Cartesian. Defaults toFalse.- 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 toNone, 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
sxformcarries 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 toFalse.- 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
Trueif 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 toNone, 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 thetide_referencenumber: a solid tide and a pole tide keep their different nominal numbers and move together, sotide_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\), inframeaxes, or zeros when nosurface_displacementis 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_pmcolumn ofiau_pole_partials(), per deg/day. The velocity rows are (km/s)/(deg/day): time cancels there, andUnitskeeps 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
Frameor 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 atbody_fixed_position + body_fixed_velocity * (t - position_epoch)at every epocht, 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
BodyOrientationstation correction.earth_orientationremains 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
BodyOrientationhere 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_correctionConstruct an Earth EOP correction.
- property mass_profile: ArrayWUnits | SCBPolynomial#
Stored constant or polynomial mass profile.
- property position_epoch#
TDB seconds past J2000 at which
body_fixed_positionholds, or None.Needed once
body_fixed_velocityis 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 singleEpochArray, in any time system, or TDB seconds; a non-finite epoch raisesInvalidEpochError.
- property surface_displacement#
Optional time-varying displacement of this station in its body-fixed frame.
Set a
SolidTideto move the station with the solid tide. Unlikebody_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 entersnominal_state()and every estimated parameter is linearised about the displaced point.Any object exposing
state_displacement(position, epoch, frame)and returning six components, as anArrayWUnitsor bare km and km/s, works, such asPoleTideandOceanLoading. 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_displacementmodel withstate_displacement_partials, or None when none is attached.
Notes
A
SolidTideand aPoleTidecarry 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:
ValueErrorA
position_epochwas not finite.