boule.Sphere
Contents
boule.Sphere#
 class boule.Sphere(name, radius, geocentric_grav_const, angular_velocity, long_name=None, reference=None)[source]#
A rotating sphere (zeroflattening 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 latitudedependent centrifugal potential.
This class is readonly: 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 semiaxis, 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

Calculate normal gravitation at any 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
 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
 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.