PoleTide

class PoleTide(pole_x: float, pole_y: float, central_body: str = 'EARTH', love_h2: float = None, shida_l2: float = None)

Bases: object

Pole-tide displacement of a surface point.

The pole tide is the solid body’s response to the wander of its rotation axis. Polar motion moves the rotation axis relative to the crust, which changes the centrifugal potential felt at the surface. The body deforms in response, like it does under the solid tide, and a station moves by up to about 2.5 cm radially and 7 mm horizontally at Earth.

With \(X, Y\) the pole coordinates, \(\bar X, \bar Y\) the mean pole, \(\phi, \lambda\) the geocentric latitude and longitude of the station at radius \(r\), and \(\omega^2 r^2/g\) with \(g = GM/r^2\), the displacement is (Moyer, with IERS Conventions (2010), eq. 7.26):

\[\begin{split}\Delta r &= -\frac{h_2}{2}\frac{\omega^2 r^2}{g}\sin 2\phi \left[(X - \bar X)\cos\lambda - (Y - \bar Y)\sin\lambda\right] \\ \Delta n &= -l_2\frac{\omega^2 r^2}{g}\cos 2\phi \left[(X - \bar X)\cos\lambda - (Y - \bar Y)\sin\lambda\right] \\ \Delta e &= l_2\frac{\omega^2 r^2}{g}\sin\phi \left[(X - \bar X)\sin\lambda + (Y - \bar Y)\cos\lambda\right]\end{split}\]

Parameters:

pole_x, pole_yArrayWUnits or float

Pole coordinates \(X, Y\); bare numbers are radians, and they are stored as radians. They are the same numbers as pole_x and pole_y.

central_bodystr, optional

Deformed body, default EARTH. Its GM and the rotation rate set the scale. It must be listed in NOMINAL_RESPONSE.

love_h2, shida_l2float, optional

Love and Shida numbers of the response. Default to Constants.EARTH_POLE_TIDE.

Attributes:

love_h2

mean_pole

\((\bar X, \bar Y)\) in radians, from the degree-2, order-1

shida_l2

Methods

displacement(position_body_fixed[, epoch, frame])	Pole-tide displacement of a body-fixed point.
state_displacement(position_body_fixed[, ...])	Pole-tide displacement and its body-fixed rate.
state_displacement_partials(position_body_fixed)	Love/Shida sensitivity of the displacement and of its body-fixed rate.
state_displacement_pole_partials(...[, ...])	Pole-coordinate sensitivity of the displacement and of its rate.

Notes

The pole is held constant, so the displacement does not vary in time and its body-fixed rate is zero. At Earth the pole moves a few milliarcseconds a day, a rate of about 1e-12 km/s, which is far below Doppler noise.

The displacement is linear in \(h_2\) and \(l_2\) and, separately, in the pole offset, so state_displacement_partials() and state_displacement_pole_partials() are exact. The second is what lets an estimated eop_delta_pole_x/eop_delta_pole_y move the pole tide along with the station rotation.

The east component takes the sign of IERS eq. 7.26, which is also the sign the centrifugal potential gives. Moyer prints the opposite sign. Using that sign would move the station by at most about 1 mm.

References

Moyer, T. D., Formulation for Observed and Computed Values of Deep Space Network Data Types for Navigation, JPL Publication 00-7, 2000.

IERS Conventions (2010), IERS Technical Note 36, Section 7.1.4.

displacement(position_body_fixed, epoch: float = None, frame: str = None) → ArrayWUnits

Pole-tide displacement of a body-fixed point.

Parameters:

position_body_fixedArrayWUnits, ArrayWFrame or array_like, shape (3,)

Undisplaced position in axes whose z is the reference pole that pole_x and pole_y are measured from (ITRF at Earth). Bare numbers are km.

epochfloat, optional

TDB seconds past J2000. Not used, because the pole is constant; it is accepted so the call matches the other surface-displacement models. Defaults to None.

framestr, optional

Not used, for the same reason. Defaults to None.

Returns:

ArrayWUnits

Displacement in km, shape (3,), in the axes of the position.

Raises:

UndefinedVerticalError

If the position is at the body centre or on the rotation axis.

state_displacement(position_body_fixed, epoch: float = None, frame: str = None) → ArrayWUnits

Pole-tide displacement and its body-fixed rate.

The rate is zero because the pole is constant; see Notes of the class. This is the method a GroundStation calls through its surface_displacement.

Parameters:

position_body_fixedArrayWUnits, ArrayWFrame or array_like, shape (3,)

Undisplaced position in axes whose z is the reference pole that pole_x and pole_y are measured from (ITRF at Earth). Bare numbers are km.

epochfloat, optional

TDB seconds past J2000. Not used, because the pole is constant. Defaults to None.

framestr, optional

Not used. Defaults to None.

Returns:

ArrayWUnits

Displacement and rate, km and km/s, shape (6,).

Raises:

UndefinedVerticalError

If the position is at the body centre or on the rotation axis.

state_displacement_partials(position_body_fixed, epoch: float = None, frame: str = None) → ArrayWUnits

Love/Shida sensitivity of the displacement and of its body-fixed rate.

Parameters:

position_body_fixedArrayWUnits, ArrayWFrame or array_like, shape (3,)

Undisplaced position; see displacement(). Bare numbers are km.

epochfloat, optional

Not used, because the pole is constant. Defaults to None.

framestr, optional

Not used. Defaults to None.

Returns:

ArrayWUnits

(6, 2) Jacobian in km and km/s per unit Love or Shida number, columns \(h_2\) and \(l_2\), the same columns as state_displacement_partials(). The rate rows are zero.

Raises:

UndefinedVerticalError

If the position is at the body centre or on the rotation axis.

Notes

\(h_2\) scales only the radial term and \(l_2\) only the two horizontal ones, so each column is the displacement at a unit number and zero for the other: exact, not a linearization.

state_displacement_pole_partials(position_body_fixed, epoch: float = None, frame: str = None) → ArrayWUnits

Pole-coordinate sensitivity of the displacement and of its rate.

Parameters:

position_body_fixedArrayWUnits, ArrayWFrame or array_like, shape (3,)

Undisplaced position; see displacement(). Bare numbers are km.

epochfloat, optional

Not used, because the pole is constant. Defaults to None.

framestr, optional

Not used. Defaults to None.

Returns:

ArrayWUnits

(6, 2) Jacobian in km/rad and km/s/rad, columns pole_x and pole_y. The rate rows are zero.

Raises:

UndefinedVerticalError

If the position is at the body centre or on the rotation axis.

Notes

The displacement is linear in the offset from the mean pole, so each column is the displacement for a unit offset in that coordinate: exact. A GroundStation sums these through pole_tide_partials() so an estimated eop_delta_pole_x/eop_delta_pole_y moves this tide too.

NOMINAL_RESPONSE = {'EARTH': PoleTideInfo(love_h2=0.609, shida_l2=0.0852, c21=-1.7e-10, s21=1.19e-09, j2=0.00048417)}

Central bodies with a nominal response, each a PoleTideInfo from Constants.

POLE_PARTIAL_UNITS = (km/rad, km/rad, km/rad, km/(sec*rad), km/(sec*rad), km/(sec*rad))

Row units of state_displacement_pole_partials().

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

Row units of state_displacement() and of its Love/Shida partials.

central_body: str = 'EARTH'

love_h2: float = None

property mean_pole: tuple

\((\bar X, \bar Y)\) in radians, from the degree-2, order-1 harmonics of NOMINAL_RESPONSE.

pole_x: float

pole_y: float

shida_l2: float = None

exception UndefinedVerticalError

Bases: ValueError

Raised when the position is at the body centre or on the rotation axis. The east direction is undefined there.

exception UnknownPoleTideResponseError

Bases: ValueError

Raised by the constructor when no pole-tide response is known for the central body. The mean pole and the rotation rate are the body’s own, so any body other than Earth needs a PoleTideInfo in Constants.