boule.Ellipsoid

boule.Ellipsoid#

class boule.Ellipsoid(name, semimajor_axis, flattening, geocentric_grav_const, angular_velocity, long_name=None, reference=None, comments=None)[source]#

A rotating oblate ellipsoid.

The ellipsoid is defined by four parameters: semimajor axis, flattening, geocentric gravitational constant, and angular velocity. It spins around its semiminor axis and has constant gravity potential at its surface. The internal density structure of the ellipsoid is unspecified but must be such that the constant potential condition is satisfied.

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.

Parameters:

namestr: A short name for the ellipsoid, for example "WGS84".
semimajor_axisfloat: The semimajor axis of the ellipsoid. The equatorial (large) radius. Definition: \(a\). Units: \(m\).
flatteningfloat: The (first) flattening of the ellipsoid. Definition: \(f = (a - b)/a\). Units: adimensional.
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}\).
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).

Notes

Caution

Use boule.Sphere if you desire zero flattening because there are singularities for this particular case in the normal gravity calculations.

Examples

We can define an ellipsoid by setting the 4 key numerical parameters and some metadata about where they came from:

>>> ellipsoid = Ellipsoid(
...     name="WGS84",
...     long_name="World Geodetic System 1984",
...     semimajor_axis=6378137,
...     flattening=1 / 298.257223563,
...     geocentric_grav_const=3986004.418e8,
...     angular_velocity=7292115e-11,
...     reference="Hofmann-Wellenhof & Moritz (2006)",
...     comments="This is the same as the boule WGS84 ellipsoid.",
... )
>>> print(ellipsoid) 
WGS84 - World Geodetic System 1984
Oblate ellipsoid:
  • Semimajor axis: 6378137 m
  • Flattening: 0.0033528106647474805
  • GM: 398600441800000.0 m³/s²
  • Angular velocity: 7.292115e-05 rad/s
Source:
  Hofmann-Wellenhof & Moritz (2006)
Comments:
  This is the same as the boule WGS84 ellipsoid.

>>> print(ellipsoid.long_name)
World Geodetic System 1984

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

>>> print(f"{ellipsoid.semiminor_axis:.4f} m")
6356752.3142 m
>>> print(f"{ellipsoid.linear_eccentricity:.8f} m")
521854.00842339 m
>>> print(f"{ellipsoid.first_eccentricity:.13e}")
8.1819190842621e-02
>>> print(f"{ellipsoid.second_eccentricity:.13e}")
8.2094437949696e-02
>>> print(f"{ellipsoid.mean_radius:.4f} m")
6370994.4018 m
>>> print(f"{ellipsoid.semiaxes_mean_radius:.4f} m")
6371008.7714 m
>>> print(f"{ellipsoid.volume_equivalent_radius:.4f} m")
6371000.7900 m
>>> print(f"{ellipsoid.mass:.10e} kg")
5.9721684941e+24 kg
>>> print(f"{ellipsoid.mean_density:.0f} kg/m³")
5513 kg/m³
>>> print(f"{ellipsoid.volume * 1e-9:.5e} km³")
1.08321e+12 km³
>>> print(f"{ellipsoid.area:.10e} m²")
5.1006562172e+14 m²
>>> print(f"{ellipsoid.area_equivalent_radius:0.4f} m")
6371007.1809 m
>>> print(f"{ellipsoid.gravity_equator:.10f} m/s²")
9.7803253359 m/s²
>>> print(f"{ellipsoid.gravity_pole:.10f} m/s²")
9.8321849379 m/s²
>>> print(f"{ellipsoid.reference_normal_gravity_potential:.3f} m²/s²")
62636851.715 m²/s²

Use the class methods for calculating normal gravity and other geometric quantities.

Attributes:

area: The area of the ellipsoid.
area_equivalent_radius: The area equivalent radius of the ellipsoid.
eccentricity: Alias for the first eccentricity.
first_eccentricity: The (first) eccentricity of the ellipsoid.
gravity_equator: The norm of the gravity acceleration vector (gravitational + centrifugal accelerations) at the equator on the surface of the ellipsoid.
gravity_pole: The norm of the gravity acceleration vector (gravitational + centrifugal accelerations) at the poles on the surface of the ellipsoid.
linear_eccentricity: The linear eccentricity 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.
reference_normal_gravity_potential: The normal gravity potential on the surface of the ellipsoid.
second_eccentricity: The second eccentricity of the ellipsoid.
semiaxes_mean_radius: The arithmetic mean radius of the ellipsoid semi-axes [Moritz1988].
semimajor_axis_longitude: The semimajor axis longitude of the ellipsoid is equal to zero.
semimedium_axis: The semimedium axis of the ellipsoid is equal to its semimajor axis.
semiminor_axis: The semiminor (small/polar) axis of the ellipsoid.
thirdflattening: The third flattening of the ellipsoid (used in geodetic calculations).
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.
`ellipsoidal_harmonic_to_geodetic`(coordinates)	Convert from ellipsoidal-harmonic coordinates to geodetic coordinates.
`geocentric_radius`(latitude[, coordinate_system])	Radial distance from the center of the ellipsoid to its surface.
`geodetic_to_ellipsoidal_harmonic`(coordinates)	Convert from geodetic to ellipsoidal harmonic coordinates.
`geodetic_to_spherical`(coordinates)	Convert from geodetic to geocentric spherical coordinates.
`normal_gravitational_potential`(coordinates)	Normal gravitational potential of the ellipsoid.
`normal_gravity`(coordinates[, si_units])	Normal gravity of the ellipsoid.
`normal_gravity_potential`(coordinates)	Normal gravity potential of the ellipsoid.
`prime_vertical_radius`(sinlat)	The prime vertical radius of curvature for a given geodetic latitude.
`spherical_to_geodetic`(coordinates)	Convert from geocentric spherical to geodetic coordinates.

Attributes#

Ellipsoid.area#: The area of the ellipsoid. Definition: \(A = 2 \pi a^2 \left(1 + \dfrac{b^2}{e a^2} \text{arctanh}\,e \right)\). Units: \(m^2\).

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

Ellipsoid.eccentricity#: Alias for the first eccentricity.

Ellipsoid.first_eccentricity#: The (first) eccentricity of the ellipsoid. The ratio between the linear eccentricity and the semimajor axis. Definition: \(e = \dfrac{\sqrt{a^2 - b^2}}{a} = \sqrt{2f - f^2}\). Units: adimensional.

Ellipsoid.gravity_equator#: The norm of the gravity acceleration vector (gravitational + centrifugal accelerations) at the equator on the surface of the ellipsoid. Units: \(m/s^2\).

Ellipsoid.gravity_pole#: The norm of the gravity acceleration vector (gravitational + centrifugal accelerations) at the poles on the surface of the ellipsoid. Units: \(m/s^2\).

Ellipsoid.linear_eccentricity#: The linear eccentricity of the ellipsoid. The distance between the ellipsoid’s center and one of its foci. Definition: \(E = \sqrt{a^2 - b^2}\). Units: \(m\).

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

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

Ellipsoid.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) \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\).

Ellipsoid.reference_normal_gravity_potential#: The normal gravity potential on the surface of the ellipsoid. Definition: \(U_0 = \dfrac{GM}{E} \arctan{\dfrac{E}{b}} + \dfrac{1}{3} \omega^2 a^2\). Units: \(m^2 / s^2\).

Ellipsoid.second_eccentricity#: The second eccentricity of the ellipsoid. The ratio between the linear eccentricity and the semiminor axis. Definition: \(e^\prime = \dfrac{\sqrt{a^2 - b^2}}{b} = \dfrac{\sqrt{2f - f^2}}{1 - f}\). Units: adimensional.

Ellipsoid.semiaxes_mean_radius#: The arithmetic mean radius of the ellipsoid semi-axes [Moritz1988]. Definition: \(R_1 = (2a + b)/3\). Units: \(m\).

Ellipsoid.semimajor_axis_longitude#: The semimajor axis longitude of the ellipsoid is equal to zero. Definition: \(\lambda_a = 0\). Units: \(m\).

Ellipsoid.semimedium_axis#: The semimedium axis of the ellipsoid is equal to its semimajor axis. Units: \(m\).

Ellipsoid.semiminor_axis#: The semiminor (small/polar) axis of the ellipsoid. Definition: \(b = a (1 - f)\). Units: \(m\).

Ellipsoid.thirdflattening#: The third flattening of the ellipsoid (used in geodetic calculations). Definition: \(f^{\prime\prime}= \dfrac{a -b}{a + b}\). Units: adimensional.

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

Ellipsoid.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#

Ellipsoid.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_geodetic, height): Longitude, latitude, and geometric height coordinates of the computation points in a geodetic coordinate system. 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. Since longitude is not used in computations (the field is symmetric with longitude), it can be assigned None.

Returns:

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

Notes

The centrifugal potential \(\Phi\) at geodetic latitude \(\phi\) and height above the ellipsoid \(h\) (geometric height) is

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

in which \(N(\phi)\) is the prime vertical radius of curvature of the ellipsoid and \(\omega\) is the angular velocity.

Ellipsoid.ellipsoidal_harmonic_to_geodetic(coordinates)[source]#

Convert from ellipsoidal-harmonic coordinates to geodetic coordinates.

The geodetic datum is defined by this ellipsoid.

Parameters:

coordinatestuple = (longitude, latitude_reduced, u): Longitude, reduced (or parametric) latitude, and u (the semiminor axis of the ellipsoid that passes through the input coordinates) coordinates of the points in a ellipsoidal harmonic coordinate system. 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 u in meters. Since longitude is not affected by conversions, it can be assigned None.

Returns:

converted_coordinatestuple = (longitude, latitude_geodetic, height): The converted longitude, geodetic latitude, and geometric height in a geodetic coordinate system. The shape of each element will be compatible with the shape of the inputs. If the input longitude is None, the output will also be None. Longitude and latitude will be in degrees and height in meters.

Ellipsoid.geocentric_radius(latitude, coordinate_system='geodetic')[source]#

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

Can be calculated from either geocentric geodetic or geocentric spherical latitudes.

Parameters:

latitudefloat or array: Latitude coordinates on geodetic coordinate system in degrees.
coordinate_systemstr: The coordinate system that will be assumed for the given latitude. Should be one of: "geodetic" (default) for geodetic latitudes or "spherical" for geocentric spherical latitudes.

Returns:

geocentric_radiusfloat or array: The geocentric radius for the given latitude(s) in the same units as the ellipsoid axis.

Notes

The geocentric surface radius \(R\) is a function of the geocentric geodetic latitude \(\phi\) and the semimajor and semiminor axis, \(a\) and \(b\) [1]:

\[R(\phi) = \sqrt{ \dfrac{ (a^2\cos\phi)^2 + (b^2\sin\phi)^2 }{ (a\cos\phi)^2 + (b\sin\phi)^2 } }\]

Alternatively, the geocentric surface radius can also be calculated using the geocentric spherical latitude \(\theta\) by passing geodetic=False:

\[R(\theta) = \sqrt{ \dfrac{ 1 }{ (\frac{\cos\theta}{a})^2 + (\frac{\sin\theta}{b})^2 } }\]

This can be useful if you already have the geocentric spherical latitudes and need the geocentric radius of the ellipsoid (for example, in spherical harmonic synthesis). In these cases, the coordinate conversion route is not possible since we need the radial coordinates to do that in the first place.

References

[1]

See https://en.wikipedia.org/wiki/Earth_radius#Geocentric_radius

Ellipsoid.geodetic_to_ellipsoidal_harmonic(coordinates)[source]#

Convert from geodetic to ellipsoidal harmonic coordinates.

The geodetic datum is defined by this ellipsoid, and the coordinates are converted following [Lakshmanan1991] and [LiGotze2001].

Parameters:

coordinatestuple = (longitude, latitude_geodetic, height): Longitude, latitude, and geometric height coordinates of the points in a geodetic coordinate system. 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. Since longitude is not affected by conversions, it can be assigned None.

Returns:

converted_coordinatestuple = (longitude, latitude_reduced, u): The converted longitude, reduced (or parametric) latitude, and the coordinate u (the semiminor axis of the ellipsoid that passes through the input coordinates) in a ellipsoidal harmonic coordinate system. The shape of each element will be compatible with the shape of the inputs. If the input longitude is None, the output will also be None. Longitude and latitude will be in degrees and u in meters.

Ellipsoid.geodetic_to_spherical(coordinates)[source]#

Convert from geodetic to geocentric spherical coordinates.

The geodetic datum is defined by this ellipsoid. The coordinates are converted following [Vermeille2002].

Parameters:

coordinatestuple = (longitude, latitude_geodetic, height): Longitude, latitude, and geometric height coordinates of the points in a geodetic coordinate system. 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. Since longitude is not affected by conversions, it can be assigned None.

Returns:

converted_coordinatestuple = (longitude, latitude_spherical, radius): The converted longitude, geocentric spherical latitude, and radius in a geocentric spherical coordinate system. The shape of each element will be compatible with the shape of the inputs. If the input longitude is None, the output will also be None. Longitude and latitude will be in degrees and radius in meters.

Ellipsoid.normal_gravitational_potential(coordinates)[source]#

Normal gravitational potential of the ellipsoid.

Computes the gravitational potential generated by the ellipsoid at the given points. Does not include the centrifugal potential. See normal_gravity_potential for a version that includes the centrifugal component.

Caution

These expressions are only valid for heights on or above the surface of the ellipsoid.

Parameters:

coordinatestuple = (longitude, latitude_geodetic, height): Longitude, latitude, and geometric height coordinates of the computation points in a geodetic coordinate system. 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. Since longitude is not used in computations (the field is symmetric with longitude), it can be assigned None.

Returns:

Vfloat or array: The normal gravitational potential in m²/s².

Notes

Computes the gravitational potential generated by the ellipsoid at the given geodetic latitude \(\phi\) and height above the ellipsoid \(h\) (geometric height).

\[V(\beta, u) = \dfrac{GM}{E} \arctan{\dfrac{E}{u}} + \dfrac{1}{3} \omega^2 a^2 \dfrac{q}{q_0} P_2 (\sin \beta)\]

in which \(V\) is the gravitational potential of the ellipsoid (no centrifugal term), \(GM\) is the geocentric gravitational constant, \(E\) is the linear eccentricity, \(\omega\) is the angular rotation rate, \(q\) and \(q_0\) are auxiliary functions, \(P_2\) is the degree 2 unnormalized Legendre Polynomial, and \(u\) and \(\beta\) are ellipsoidal-harmonic coordinates corresponding to the input geodetic latitude and ellipsoidal height. See eq. 2-124 of [HofmannWellenhofMoritz2006].

Assumes that the internal density distribution of the ellipsoid is such that the gravity potential is constant at its surface.

Ellipsoid.normal_gravity(coordinates, si_units=False)[source]#

Normal gravity of the ellipsoid.

Computes the magnitude of the gradient of the gravity potential generated by this ellipsoid at any point outside the ellipsoid. Based on the closed-form expressions by [Lakshmanan1991] and corrected by [LiGotze2001]. This means that the free-air correction is not necessary to calculate normal gravity at the observation points.

Caution

These expressions are only valid for heights on or above the surface of the ellipsoid.

Parameters:

coordinatestuple = (longitude, latitude_geodetic, height): Longitude, latitude, and geometric height coordinates of the computation points in a geodetic coordinate system. 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. Since longitude is not used in computations (the field is symmetric with longitude), it can be assigned None.
si_unitsbool: Return the value in mGal (False, default) or m/s² (True).

Returns:

gammafloat or array: The normal gravity in mGal or m/s².

Notes

Normal gravity is defined as the magnitude of the gradient of the gravity potential generated by a reference ellipsoid at the given geodetic latitude \(\phi\) and height above the ellipsoid \(h\) (geometric height).

\[\gamma(\phi, h) = \|\vec{\nabla}U(\phi, h)\|\]

in which \(U = V + \Phi\) is the gravity potential of the ellipsoid, \(V\) is the gravitational potential of the ellipsoid, and \(\Phi\) is the centrifugal potential.

The equations used here assume that the internal density distribution of the ellipsoid is such that the gravity potential is constant at its surface. The specific internal density distribution is undefined.

Ellipsoid.normal_gravity_potential(coordinates)[source]#

Normal gravity potential of the ellipsoid.

Computes the gravity potential (gravitational + centrifugal) generated by the ellipsoid at the given points. See normal_gravitational_potential for a version that is purely gravitational.

Caution

These expressions are only valid for heights on or above the surface of the ellipsoid.

Parameters:

coordinatestuple = (longitude, latitude_geodetic, height): Longitude, latitude, and geometric height coordinates of the computation points in a geodetic coordinate system. 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. Since longitude is not used in computations (the field is symmetric with longitude), it can be assigned None.

Returns:

Vfloat or array: The normal gravity potential in m²/s².

Notes

Computes the gravity potential generated by the ellipsoid at the given geodetic latitude \(\phi\) and height above the ellipsoid \(h\) (geometric height).

\[U(\beta, u) = \dfrac{GM}{E} \arctan{\dfrac{E}{u}} + \dfrac{1}{2} \omega^2 a^2 \dfrac{q}{q_0} \left(\sin^2 \beta - \dfrac{1}{3}\right) + \dfrac{1}{2} \omega^2 \left(u^2 + E^2\right) \cos^2 \beta\]

in which \(U\) is the gravity potential of the ellipsoid, \(GM\) is the geocentric gravitational constant, \(E\) is the linear eccentricity, \(\omega\) is the angular rotation rate, \(q\) and \(q_0\) are auxiliary functions, and \(u\) and \(\beta\) are ellipsoidal-harmonic coordinates corresponding to the input geodetic latitude and ellipsoidal height. See eq. 2-126 of [HofmannWellenhofMoritz2006].

Assumes that the internal density distribution of the ellipsoid is such that the gravity potential is constant at its surface.

Ellipsoid.prime_vertical_radius(sinlat)[source]#

The prime vertical radius of curvature for a given geodetic latitude.

Note

This function receives the sine of the latitude as input to avoid repeated computations of trigonometric functions in methods/functions that rely on it.

Parameters:

sinlatfloat or array_like: Sine of the geocentric geodetic latitude.

Returns:

prime_vertical_radiusfloat or array_like: Prime vertical radius given in the same units as the semi-major axis

Notes

The prime vertical radius of curvature \(N\) is defined as [2]:

\[N(\phi) = \frac{a}{\sqrt{1 - e^2 \sin^2(\phi)}}\]

Where \(a\) is the semimajor axis and \(e\) is the first eccentricity.

References

[2]

See https://en.wikipedia.org/wiki/Earth_radius#Prime_vertical

Ellipsoid.spherical_to_geodetic(coordinates)[source]#

Convert from geocentric spherical to geodetic coordinates.

The geodetic datum is defined by this ellipsoid. The coordinates are converted following [Vermeille2002].

Parameters:

coordinatestuple = (longitude, latitude_spherical, height): Longitude, latitude, and radius coordinates of the points in a geocentric spherical coordinate system. 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 radius in meters. Since longitude is not affected by conversions, it can be assigned None.

Returns:

converted_coordinatestuple = (longitude, latitude_geodetic, height): The converted longitude, geodetic latitude, and geometric height in a geodetic coordinate system. The shape of each element will be compatible with the shape of the inputs. If the input longitude is None, the output will also be None. Longitude and latitude will be in degrees and height in meters.

boule.Ellipsoid

Contents

boule.Ellipsoid#

Attributes#

Methods#