Ctrl+K

boule.TriaxialEllipsoid

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:

  • name (str) – A short name for the ellipsoid, for example "WGS84".

  • semimajor_axis (float) – The semimajor (largest) axis of the ellipsoid. Definition: \(a\). Units: \(m\).

  • semimedium_axis (float) – The semimedium (middle) axis of the ellipsoid. Definition: \(b\). Units: \(m\).

  • semiminor_axis (float) – The semiminor (smallest) axis of the ellipsoid. Definition: \(c\). Units: \(m\).

  • geocentric_grav_const (float) – 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_velocity (float) – The angular velocity of the rotating ellipsoid. Definition: \(\omega\). Units: \(\\rad.s^{-1}\).

  • semimajor_axis_longitude (float) – Longitude coordinate of the semimajor axis in the x-y plane. Optional, default value is 0.0.

  • long_name (str or None) – A long name for the ellipsoid, for example "World Geodetic System 1984" (optional).

  • reference (str or None) – Citation for the ellipsoid parameter values (optional).

  • comments (str 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=286_300,
...     semimedium_axis=278_600,
...     semiminor_axis=223_200,
...     geocentric_grav_const=1.729094e10,
...     angular_velocity=326.71050958367e-6,
...     reference=(
...         "Russell, C. T., Raymond, C. A., Coradini, A., McSween, "
...         "H. Y., Zuber, M. T., Nathues, A., et al. (2012). Dawn at "
...         "Vesta: Testing the Protoplanetary Paradigm. Science. "
...         "doi:10.1126/science.1219381"
...     ),
... )
>>> print(ellipsoid) 
TriaxialEllipsoid(name='VESTA', ...)
>>> 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")
259813 m
>>> print(f"{ellipsoid.semiaxes_mean_radius:.0f} m")
262700 m
>>> print(f"{ellipsoid.area:.10e} m²")
8.6562393883e+11 m²
>>> print(f"{ellipsoid.area_equivalent_radius:0.0f} m")
262458 m
>>> print(f"{ellipsoid.volume_equivalent_radius:.0f} m")
261115 m
>>> print(f"{ellipsoid.mass:.10e} kg")
2.5906746775e+20 kg
>>> print(f"{ellipsoid.mean_density:.0f} kg/m³")
3474 kg/m³
>>> print(f"{ellipsoid.volume * 1e-9:.0f} km³")
74573626 km³

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#

List of methods

TriaxialEllipsoid.geocentric_radius(...)

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

Methods documentation

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:

  • longitude (float or array) – Longitude coordinates on spherical coordinate system in degrees.

  • latitude (float or array) – Latitude coordinates on spherical coordinate system in degrees.

Returns:

geocentric_radius (float 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.

Tip

No elevation is taken into account.

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.

Contents