`OceanLoading`#

class OceanLoading(amplitudes: tuple, phases: tuple, rate_step: float = 60.0)#

Bases: object

Ocean-loading displacement of a station, from BLQ coefficients.

Ocean loading is the crust’s response to the weight of the ocean tide. The tide moves a large mass of water over the crust twice a day, and the crust sags under it. A coastal station moves by up to a few centimetres, and an inland one by a few millimetres. The response depends on the station and the ocean model, so it is given per station as the amplitudes and phases of a BLQ table, such as those from the Onsala loading service (http://holt.oso.chalmers.se/loading/).

For each constituent $i$ with astronomical argument $\theta_i + \chi_i$ (see OceanLoadingInfo) and nodal corrections $f_i, u_i$, the displacement in m is (Moyer, with the nodal corrections of IERS Conventions (2010), eq. 7.16):

\[\begin{split}\Delta z &= \sum_i f_i A^r_i \cos(\theta_i + \chi_i + u_i - \phi^r_i) \\ \Delta n &= -\sum_i f_i A^S_i \cos(\theta_i + \chi_i + u_i - \phi^S_i) \\ \Delta e &= -\sum_i f_i A^W_i \cos(\theta_i + \chi_i + u_i - \phi^W_i)\end{split}\]

Here $A$ and $\phi$ are the BLQ amplitudes and Greenwich phase lags of the radial, south and west components.

Parameters:

amplitudesarray_like, shape (3, 11): Amplitudes, m. The rows are radial, west and south, and the columns are the constituents of Constants.EARTH_OCEAN_LOADING, in the order of a BLQ table.
phasesarray_like, shape (3, 11): Greenwich phase lags, degrees, in the same layout.
rate_stepfloat, optional: Half-interval in seconds for the central difference that supplies the body-fixed rate, default 60.

Methods

`arguments`(epoch[, frame])	Astronomical arguments $\theta_i + \chi_i$ of the constituents, degrees.
`displacement`(position_body_fixed, epoch[, frame])	Ocean-loading displacement of the station.
`earth_rotation_angle`(epoch, frame)	Earth rotation angle of an Earth-fixed frame, radians.
`from_blq`(path, station[, rate_step])	Read one station's coefficients from a BLQ file.
`nodal_corrections`(epoch)	Nodal factors $f_i$ and angles $u_i$ of the constituents.
`state_displacement`(position_body_fixed, epoch)	Ocean-loading displacement and its body-fixed rate.

Notes

The nodal corrections $f$ and $u$ follow the 18.6-year regression of the lunar node (nodal_corrections()). Moyer leaves them out; they scale the lunar terms by up to 4% for M2 and 40% for Mf.

The Doodson variable $\tau$ needs UT1. When the station’s Earth-fixed frame is given it is read from that frame’s rotation, so the phase follows the same Earth rotation that places the station (see arguments()); without a frame UTC stands in for UT1, which moves the phase by at most a few millidegrees.

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.2, eq. 7.16.

classmethod from_blq(path, station: str, rate_step: float = 60.0) → OceanLoading#

Read one station’s coefficients from a BLQ file.

Parameters:

pathstr or path-like: BLQ file. Lines starting with $$ are comments. Each station is a name line followed by six rows of numbers: the radial, west and south amplitudes in m, then their phases in degrees.
stationstr: Station name as written in the file. Case and repeated spaces are ignored.
rate_stepfloat, optional: Half-interval in seconds for the central difference that supplies the body-fixed rate, default 60.

Returns:

OceanLoading: Model holding that station’s amplitudes and phases.

Raises:

StationNotFoundError: If the station is not in the file, or its name is not followed by six rows of numbers.

static arguments(epoch: float, frame: str = None) → ndarray#

Astronomical arguments $\theta_i + \chi_i$ of the constituents, degrees.

Parameters:

epochfloat: TDB seconds past J2000.
framestr, optional: Earth-fixed frame whose rotation supplies UT1 for $\tau$, through earth_rotation_angle() and GMST from IERS 2010 eq. 5.32. When None, the default, UTC stands in for UT1.

Returns:

numpy.ndarray: One argument per constituent of Constants.EARTH_OCEAN_LOADING.

References

IERS Conventions (2010), IERS Technical Note 36, Section 5.5.7, eq. 5.32.

static earth_rotation_angle(epoch: float, frame: str) → float#

Earth rotation angle of an Earth-fixed frame, radians.

Parameters:

epochfloat: TDB seconds past J2000.
framestr: Earth-fixed frame, e.g. "ITRF93".

Returns:

float: Angle from the celestial to the terrestrial intermediate origin, in $(-\pi, \pi]$.

Notes

With $M$ the J2000-to-frame rotation, the third row of $M$ is the pole $(X, Y, Z)$ in J2000. The CIO-based matrix $Q = R_3(-E) R_2(-d) R_3(E) R_3(s)$ (IERS 2010 eq. 5.6) with $E = \mathrm{atan2}(Y, X)$, $d = \arccos Z$ (eq. 5.7) and $s \approx -XY/2$, the leading term of eq. 5.9, leaves $M Q = R_3(\theta)$ up to the polar motion, whose effect on $\theta$ is second order. Through the IERS definition $\theta = 2\pi(0.7790572732640 + 1.00273781191135448\,D_U)$ (eq. 5.14), with $D_U$ the UT1 Julian date minus 2451545.0, this angle is UT1: for ITRF93 it recovers the tabulated UT1 - UTC to tens of microseconds.

References

IERS Conventions (2010), IERS Technical Note 36, Section 5.4.4, eqs. 5.6, 5.7 and 5.9, and Section 5.5.3, eq. 5.14.

static nodal_corrections(epoch: float) → tuple#

Nodal factors $f_i$ and angles $u_i$ of the constituents.

Parameters:

epochfloat: TDB seconds past J2000.

Returns:

tuple of numpy.ndarray: (f, u): the amplitude factors, and the phase corrections in degrees, one per constituent of Constants.EARTH_OCEAN_LOADING.

Notes

$f = \sum_k a_k \cos kN$ and $u = \sum_k b_k \sin kN$, with $N$ the longitude of the Moon’s ascending node, the Delaunay $\Omega$.

References

Pugh, D. T., Tides, Surges and Mean Sea-Level, Wiley, 1987, Table 4.3, after Schureman, P., Manual of Harmonic Analysis and Prediction of Tides, US Coast and Geodetic Survey Special Publication 98, 1958.

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

Ocean-loading displacement of the station.

Parameters:

position_body_fixedArrayWUnits, ArrayWFrame or array_like, shape (3,): Undisplaced position, Earth-fixed. It only sets the local vertical, east and north directions. Bare numbers are km.
epochfloat or EpochArray: TDB seconds past J2000.
framestr or Frame, optional: Earth-fixed frame of the position. Its rotation supplies UT1 for the arguments (arguments()); the displacement is returned in the axes of the position. When None, the default, UTC stands in for UT1.

Returns:

ArrayWUnits: Displacement in km, shape (3,).

Raises:

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

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

Ocean-loading displacement and its body-fixed rate.

The rate is a central difference over rate_step. This is the method a GroundStation calls through its surface_displacement.

Parameters:

position_body_fixedArrayWUnits, ArrayWFrame or array_like, shape (3,): Undisplaced position, Earth-fixed. It only sets the local vertical, east and north directions. Bare numbers are km.
epochfloat or EpochArray: TDB seconds past J2000.
framestr or Frame, optional: Earth-fixed frame of the position, passed to displacement(). 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_UNITS = (km, km, km, km/sec, km/sec, km/sec)#: Row units of state_displacement().

amplitudes: tuple#

phases: tuple#

rate_step: float = 60.0#

exception CoefficientShapeError#

Bases: ValueError

Raised by the constructor when the amplitudes or phases are not 3 x (number of constituents) finite values.

exception StationNotFoundError#

Bases: KeyError

Raised by from_blq() when the station is not in the file, or its block has fewer than six rows of coefficients.

exception UndefinedVerticalError#

Bases: ValueError

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

`arguments`(epoch[, frame])	Astronomical arguments \(\theta_i + \chi_i\) of the constituents, degrees.
`displacement`(position_body_fixed, epoch[, frame])	Ocean-loading displacement of the station.
`earth_rotation_angle`(epoch, frame)	Earth rotation angle of an Earth-fixed frame, radians.
`from_blq`(path, station[, rate_step])	Read one station's coefficients from a BLQ file.
`nodal_corrections`(epoch)	Nodal factors \(f_i\) and angles \(u_i\) of the constituents.
`state_displacement`(position_body_fixed, epoch)	Ocean-loading displacement and its body-fixed rate.