boule.TriaxialEllipsoid#

class boule.TriaxialEllipsoid(name, semimajor_axis, semimedium_axis, semiminor_axis, geocentric_grav_const, angular_velocity, semimajor_axis_longitude=0.0, long_name=None, reference=None, comments=None)[source]#

A rotating triaxial ellipsoid.

The ellipsoid is defined by five parameters: semimajor axis, semimedium axis, semiminor axis, geocentric gravitational constant, and angular velocity. The ellipsoid spins around it’s smallest semiminor axis, which is aligned with the Cartesian z coordinate axis. The semimajor and semimedium axes are in the x-y plane, and if not specified otherwise, coincide with the Cartesian x and y axes.

This class is read-only: Input parameters and attributes cannot be changed after instantiation.

Units: All input parameters and derived attributes are in SI units.

Attention

Most gravity calculations have not been implemented yet for triaxial ellipsoids. If you’re interested in this feature or would like to help implement it, please get in touch.

Parameters:

namestr: A short name for the ellipsoid, for example "WGS84".
semimajor_axisfloat: The semimajor (largest) axis of the ellipsoid. Definition: \(a\). Units: \(m\).
semimedium_axisfloat: The semimedium (middle) axis of the ellipsoid. Definition: \(b\). Units: \(m\).
semiminor_axisfloat: The semiminor (smallest) axis of the ellipsoid. Definition: \(c\). Units: \(m\).
geocentric_grav_constfloat: The geocentric gravitational constant. The product of the mass of the ellipsoid \(M\) and the gravitational constant \(G\). Definition: \(GM\). Units: \(m^3.s^{-2}\).
angular_velocityfloat: The angular velocity of the rotating ellipsoid. Definition: \(\omega\). Units: \(\\rad.s^{-1}\).
semimajor_axis_longitudefloat: Longitude coordinate of the semimajor axis in the x-y plane. Optional, default value is 0.0.
long_namestr or None: A long name for the ellipsoid, for example "World Geodetic System 1984" (optional).
referencestr or None: Citation for the ellipsoid parameter values (optional).
commentsstr or None: Additional comments regarding the ellipsoid (optional).

Examples

We can define an ellipsoid by setting the 5 key numerical parameters:

>>> ellipsoid = TriaxialEllipsoid(
...     name="Vesta",
...     long_name="Vesta Triaxial Ellipsoid",
...     semimajor_axis=280_413,
...     semimedium_axis=274_572,
...     semiminor_axis=231_253,
...     geocentric_grav_const=17.288e9,
...     angular_velocity=3.267e-4,
...     semimajor_axis_longitude=8.29,
...     reference="Karimi et al. (2017)",
...     comments="This is the same as the VestaTriaxial2017 ellipsoid."
... )
>>> print(ellipsoid) 
Vesta - Vesta Triaxial Ellipsoid
Triaxial ellipsoid:
  • Semimajor axis: 280413 m
  • Semimedium axis: 274572 m
  • Semiminor axis: 231253 m
  • Semimajor axis longitude: 8.29°
  • GM: 17288000000.0 m³/s²
  • Angular velocity: 0.0003267 rad/s
Source:
  Karimi et al. (2017)
Comments:
  This is the same as the VestaTriaxial2017 ellipsoid.

>>> print(ellipsoid.long_name)
Vesta Triaxial Ellipsoid

The class then defines several derived attributes based on the input parameters:

>>> print(f"{ellipsoid.mean_radius:.0f} m")
260344 m
>>> print(f"{ellipsoid.semiaxes_mean_radius:.0f} m")
262079 m
>>> print(f"{ellipsoid.area:.10e} m²")
8.6210266337e+11 m²
>>> print(f"{ellipsoid.area_equivalent_radius:0.0f} m")
261924 m
>>> print(f"{ellipsoid.volume_equivalent_radius:.0f} m")
261124 m
>>> print(f"{ellipsoid.mass:.10e} kg")
2.5902341819e+20 kg
>>> print(f"{ellipsoid.mean_density:.0f} kg/m³")
3473 kg/m³
>>> print(f"{ellipsoid.volume * 1e-9:.0f} km³")
74581373 km³

Attributes:

area: The area of the ellipsoid.
area_equivalent_radius: The area equivalent radius of the ellipsoid.
equatorial_flattening: The equatorial flattening of the ellipsoid.
mass: The mass of the ellipsoid.
mean_density: The mean density of the ellipsoid.
mean_radius: The mean radius of the ellipsoid.
meridional_flattening: The meridional flattening of the ellipsoid in the meridian plane containing the semi-major axis.
semiaxes_mean_radius: The arithmetic mean radius of the ellipsoid semi-axes.
volume: The volume bounded by the ellipsoid.
volume_equivalent_radius: The volume equivalent radius of the ellipsoid.

Methods

`centrifugal_potential`(coordinates)	Centrifugal potential of the rotating ellipsoid.
`geocentric_radius`(longitude, latitude)	Radial distance from the center of the ellipsoid to its surface.

Attributes#

TriaxialEllipsoid.area#: The area of the ellipsoid. Definition: \(A = 3 V R_G(a^{-2}, b^{-2}, c^{-2})\), in which \(R_G\) is the completely-symmetric elliptic integral of the second kind. Units: \(m^2\).

TriaxialEllipsoid.area_equivalent_radius#: The area equivalent radius of the ellipsoid. Definition: \(R_2 = \sqrt{A / (4 \pi)}\). Units: \(m\).

TriaxialEllipsoid.equatorial_flattening#: The equatorial flattening of the ellipsoid. Definition: \(f_b = \frac{a - b}{a}\). Units: adimensional.

TriaxialEllipsoid.mass#: The mass of the ellipsoid. Definition: \(M = GM / G\). Units: \(kg\).

TriaxialEllipsoid.mean_density#: The mean density of the ellipsoid. Definition: \(\rho = M / V\). Units: \(kg / m^3\).

TriaxialEllipsoid.mean_radius#

The mean radius of the ellipsoid. This is equivalent to the degree 0 spherical harmonic coefficient of the ellipsoid shape.

Definition: \(R_0 = \dfrac{1}{4 \pi} {\displaystyle \int_0^{\pi} \int_0^{2 \pi}} r(\theta, \lambda) \sin \theta \, d\theta \, d\lambda\)

in which \(r\) is the ellipsoid spherical radius, \(\theta\) is spherical latitude, and \(\lambda\) is spherical longitude.

Units: \(m\).

TriaxialEllipsoid.meridional_flattening#: The meridional flattening of the ellipsoid in the meridian plane containing the semi-major axis. Definition: \(f_c = \frac{a - c}{a}\). Units: adimensional.

TriaxialEllipsoid.semiaxes_mean_radius#: The arithmetic mean radius of the ellipsoid semi-axes. Definition: \(R_1 = \dfrac{a + b + c}{3}\). Units: \(m\).

TriaxialEllipsoid.volume#: The volume bounded by the ellipsoid. Definition: \(V = \dfrac{4}{3} \pi a b c\). Units: \(m^3\).

TriaxialEllipsoid.volume_equivalent_radius#: The volume equivalent radius of the ellipsoid. Definition: \(R_3 = \left(\dfrac{3}{4 \pi} V \right)^{1/3}\). Units: \(m\).

Methods#

TriaxialEllipsoid.centrifugal_potential(coordinates)[source]#

Centrifugal potential of the rotating ellipsoid.

Calculate the centrifugal potential due to the rotation of the ellipsoid about its semiminor axis at the given points.

Parameters:

coordinatestuple = (longitude, latitude_spherical, height): Longitude, latitude, and height coordinates of the computation points in a geocentric spherical coordinate system. The height is measured from the surface of the ellipsoid. Each element can be a single number or an array. The shape of the arrays must be compatible. Longitude and latitude must be in degrees and height in meters.

Returns:

Phifloat or array: The centrifugal potential in m²/s².

Notes

The centrifugal potential \(\Phi\) at spherical latitude \(\phi\), spherical longitude \(\lambda\) and height above the ellipsoid \(h\) is

\[\Phi(\phi, \lambda, h) = \dfrac{1}{2} \omega^2 \left(R(\phi, lambda) + h\right)^2 \cos^2(\phi)\]

in which \(R(\phi, \lambda)\) is the radius of the ellipsoid and \(\omega\) is the angular velocity.

TriaxialEllipsoid.geocentric_radius(longitude, latitude)[source]#

Radial distance from the center of the ellipsoid to its surface.

Assumes geocentric spherical latitude and geocentric spherical longitudes. The geocentric radius is calculated following [Pěč1983].

Parameters:

longitudefloat or array: Longitude coordinates on spherical coordinate system in degrees.
latitudefloat or array: Latitude coordinates on spherical coordinate system in degrees.

Returns:

geocentric_radiusfloat or array: The geocentric radius for the given spherical latitude(s) and spherical longitude(s) in the same units as the axes of the ellipsoid.

Notes

Given geocentric spherical latitude \(\phi\) and geocentric spherical longitude \(\lambda\), the geocentric surface radius \(R\) is computed as (see Eq. 1 of [Pěč1983])

\[R(\phi, \lambda) = \frac{ a \, (1 - f_c) \, (1 - f_b) }{ \sqrt{ 1 - (2 f_c - f_c^2) \cos^2 \phi - (2 f_b - f_b^2) \sin^2 \phi - (1 - f_c)^2 (2 f_b - f_b^2) \cos^2 \phi \cos^2 (\lambda - \lambda_a) } },\]

where \(f_c\) is the meridional flattening

\[f_c = \frac{a - c}{a},\]

\(f_b\) is the equatorial flattening

\[f_b = \frac{a - b}{a},\]

with \(a\), \(b\) and \(c\) being the semi-major, semi-medium and semi-minor axes of the ellipsoid, and \(\lambda_a\) being the geocentric spherical longitude of the meridian containing the semi-major axis.

Note that [Pěč1983] use geocentric spherical co-latitude, while here we used geocentric spherical latitude.

boule.TriaxialEllipsoid

Contents

boule.TriaxialEllipsoid#

Attributes#

Methods#