boule.Sphere#

class boule.Sphere(name, radius, geocentric_grav_const, angular_velocity, long_name=None, reference=None)[source]#

A rotating sphere (zero-flattening ellipsoid).

The ellipsoid is defined by three parameters: radius, geocentric gravitational constant, and angular velocity. The internal density structure can be either homogeneous or vary radially (e.g. in homogeneous concentric spherical shells). The gravity potential of the sphere is not constant on its surface because of the latitude-dependent centrifugal potential.

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

  • name (str) – A short name for the sphere, for example "Moon".

  • radius (float) – The radius of the sphere. Definition: \(R\). Units: \(m\).

  • geocentric_grav_const (float) – The geocentric gravitational constant. The product of the mass of the sphere \(M\) and the gravitational constant \(G\). Definition: \(GM\). Units: \(m^3.s^{-2}\).

  • angular_velocity (float) – The angular velocity of the rotating sphere. Definition: \(\omega\). Units: \(\\rad.s^{-1}\).

  • long_name (str or None) – A long name for the sphere, for example "Moon Reference System" (optional).

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

Caution

Must be used instead of boule.Ellipsoid with zero flattening for gravity calculations because it is impossible for a rotating sphere to have constant gravity (gravitational + centrifugal) potential on its surface. So the underlying ellipsoid gravity calculations don’t apply and are in fact singular when the flattening is zero.

Examples

We can define a sphere by specifying the 3 key numerical parameters:

>>> sphere = Sphere(
...     name="Moon",
...     long_name="That's no moon",
...     radius=1,
...     geocentric_grav_const=2,
...     angular_velocity=0.5,
... )
>>> print(sphere) 
Sphere(name='Moon', ...)
>>> print(sphere.long_name)
That's no moon

The sphere defines semi-axis, flattening, and some eccentricities similar to Ellipsoid for compatibility with the coordinate conversion functions of pymap3d:

>>> print(sphere.semiminor_axis)
1
>>> print(sphere.semimajor_axis)
1
>>> print(sphere.first_eccentricity)
0
>>> print(sphere.eccentricity)
0
>>> print(sphere.flattening)
0
>>> print(sphere.thirdflattening)
0

Attributes#

Sphere.eccentricity#

Alias for the first eccentricity.

Sphere.first_eccentricity#

The (first) eccentricity of the sphere is equal to zero. Added for compatibility with pymap3d. Definition: \(e = \dfrac{\sqrt{a^2 - b^2}}{a} = \sqrt{2f - f^2}\). Units: adimensional.

Sphere.flattening#

The flattening of the sphere is equal to zero. Added for compatibility with pymap3d. Definition: \(f = \dfrac{a - b}{a}\). Units: adimensional.

Sphere.semimajor_axis#

The semimajor axis of the sphere is equal to its radius. Added for compatibility with pymap3d. Definition: \(a = R\). Units: \(m\).

Sphere.semiminor_axis#

The semiminor axis of the sphere is equal to its radius. Added for compatibility with pymap3d. Definition: \(b = R\). Units: \(m\).

Sphere.thirdflattening#

The third flattening of the sphere is equal to zero. Added for compatibility with pymap3d Definition: \(f^{\prime\prime}= \dfrac{a -b}{a + b}\). Units: adimensional.

Methods#

List of methods

Sphere.normal_gravitation(height[, si_units])

Calculate normal gravitation at any height.

Sphere.normal_gravity(latitude, height[, ...])

Normal gravity of the sphere at the given latitude and height.

Methods documentation

Sphere.normal_gravitation(height, si_units=False)[source]#

Calculate normal gravitation at any height.

Computes the magnitude of the gradient of the gravitational potential generated by the sphere at the given height \(h\):

\[\gamma(h) = \|\vec{\nabla}V(h)\| = \dfrac{GM}{(R + h)^2}\]

in which \(R\) is the sphere radius, \(G\) is the gravitational constant, and \(M\) is the mass of the sphere.

Caution

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

Parameters

  • height (float or array) – The height above the surface of the sphere of the computation point (in meters).

  • si_units (bool) – Return the value in mGal (False, default) or m/s² (True)

Returns

gamma (float or array) – The normal gravitation in mGal.

Examples

Normal gravitation can be calculated at any point. However as this is a sphere, only the height is used in the calculation.

>>> sphere = Sphere(
...     name="Moon",
...     long_name="That's no moon",
...     radius=1,
...     geocentric_grav_const=2,
...     angular_velocity=0.5,
... )
>>> g = sphere.normal_gravitation(height=1)
>>> print(f"{g:.2f} mGal")
50000.00 mGal
Sphere.normal_gravity(latitude, height, si_units=False)[source]#

Normal gravity of the sphere at the given latitude and height.

Computes the magnitude of the gradient of the gravity potential (gravitational + centrifugal; see [HofmannWellenhofMoritz2006]) generated by the sphere at the given spherical latitude \(\theta\) and height above the surface of the sphere \(h\):

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

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

Caution

The current implementation is only valid for heights on or above the surface of the sphere.

Parameters

  • latitude (float or array) – The spherical latitude where the normal gravity will be computed (in degrees).

  • height (float or array) – The height above the surface of the sphere of the computation point (in meters).

  • si_units (bool) – Return the value in mGal (False, default) or m/s² (True)

Returns

gamma (float or array) – The normal gravity in mGal or m/s².

Examples

Normal gravity can be calculated at any spherical latitude and height above the sphere:

>>> sphere = Sphere(
...     name="Moon",
...     long_name="That's no moon",
...     radius=1,
...     geocentric_grav_const=2,
...     angular_velocity=0.5,
... )
>>> gamma_equator = sphere.normal_gravity(latitude=0, height=0)
>>> print(f"{gamma_equator:.2f} mGal")
175000.00 mGal
>>> gamma_pole = sphere.normal_gravity(latitude=90, height=0)
>>> print(f"{gamma_pole:.2f} mGal")
200000.00 mGal

Notes

The gradient of the gravity potential is the sum of the gravitational \(\vec{g}\) and centrifugal \(\vec{f}\) accelerations for a rotating sphere:

\[\vec{\nabla}U(\theta, h) = \vec{g}(\theta, h) + \vec{f}(\theta, h)\]

The radial and latitudinal components of the two acceleration vectors are:

\[g_r = -\dfrac{GM}{(R + h)^2}\]
\[g_\theta = 0\]

and

\[f_r = \omega^2 (R + h) \cos^2 \theta\]
\[f_\theta = \omega^2 (R + h) \cos\theta\sin\theta\]

in which \(R\) is the sphere radius, \(G\) is the gravitational constant, \(M\) is the mass of the sphere, and \(\omega\) is the angular velocity.

The norm of the combined gravitational and centrifugal accelerations is:

\[\gamma(\theta, h) = \sqrt{ \left( \dfrac{GM}{(R + h)^2} \right)^2 + \left( \omega^2 (R + h) - 2\dfrac{GM}{(R + h)^2} \right) \omega^2 (R + h) \cos^2 \theta }\]

It’s worth noting that a sphere under rotation is not in hydrostatic equilibrium. Therefore unlike the oblate ellipsoid, it is not it’s own equipotential gravity surface (as is the case for the ellipsoid), the gravity potential is not constant at the surface, and the normal gravity vector is not normal to the surface of the sphere.