boule.Sphere

boule.Sphere#

class boule.Sphere(name, radius, geocentric_grav_const, angular_velocity, long_name=None, reference=None, comments=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:

namestr: A short name for the sphere, for example "Moon".
radiusfloat: The radius of the sphere. Definition: \(R\). Units: \(m\).
geocentric_grav_constfloat: 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_velocityfloat: The angular velocity of the rotating sphere. Definition: \(\omega\). Units: \(\\rad.s^{-1}\).
long_namestr or None: A long name for the sphere, for example "Moon Reference System" (optional).
referencestr or None: Citation for the sphere parameter values (optional).
commentsstr or None: Additional comments regarding the ellipsoid (optional).

Notes

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="Moon Spheroid",
...     radius=1737151,
...     geocentric_grav_const=4902800070000.0,
...     angular_velocity=2.6617073e-06,
...     reference="Wieczorek (2015)",
...     comments="This is the same as the boule Moon2015 spheroid."
... )
>>> print(sphere) 
Moon - Moon Spheroid
Spheroid:
  • Radius: 1737151 m
  • GM: 4902800070000.0 m³/s²
  • Angular velocity: 2.6617073e-06 rad/s
Source:
  Wieczorek (2015)
Comments:
  This is the same as the boule Moon2015 spheroid.

>>> print(sphere.long_name)
Moon Spheroid

The sphere defines semi-axess, flattening, and some eccentricities similar to Ellipsoid for compatibility:

>>> print(sphere.semiminor_axis)
1737151
>>> print(sphere.semimajor_axis)
1737151
>>> print(sphere.first_eccentricity)
0
>>> print(sphere.eccentricity)
0
>>> print(sphere.flattening)
0
>>> print(sphere.thirdflattening)
0
>>> print(sphere.mean_radius)
1737151
>>> print(sphere.semiaxes_mean_radius)
1737151
>>> print(f"{sphere.volume_equivalent_radius:.1f} m")
1737151.0 m
>>> print(f"{sphere.volume:.12e} m³")
2.195843181718e+19 m³
>>> print(f"{sphere.area:.12e} m²")
3.792145613798e+13 m²
>>> print(sphere.area_equivalent_radius)
1737151
>>> print(f"{sphere.mass:.12e} kg")
7.345789176393e+22 kg
>>> print(f"{sphere.mean_density:.0f} kg/m³")
3345 kg/m³
>>> print(f"{sphere.reference_normal_gravitational_potential:.3f} m²/s²")
2822322.337 m²/s²

Attributes:

area: The area of the sphere.
area_equivalent_radius: The area equivalent radius of the sphere is equal to its radius.
eccentricity: Alias for the first eccentricity.
first_eccentricity: The (first) eccentricity of the sphere is equal to zero.
flattening: The flattening of the sphere is equal to zero.
mass: The mass of the sphere.
mean_density: The mean density of the sphere.
mean_radius: The mean radius of the ellipsoid is equal to its radius.
reference_normal_gravitational_potential: The normal gravitational potential on the surface of the sphere.
semiaxes_mean_radius: The arithmetic mean radius of the ellipsoid semi-axes is equal to its radius.
semimajor_axis: The semimajor axis of the sphere is equal to its radius.
semimajor_axis_longitude: The semimajor axis longitude of the sphere is equal to zero.
semimedium_axis: The semimedium axis of the sphere is equal to its radius.
semiminor_axis: The semiminor axis of the sphere is equal to its radius.
thirdflattening: The third flattening of the sphere is equal to zero.
volume: The volume of the sphere.
volume_equivalent_radius: The volume equivalent radius of the sphere is equal to its radius.

Methods

`centrifugal_potential`(latitude, height)	Centrifugal potential at the given latitude and height above the sphere.
`normal_gravitation`(height[, si_units])	Calculate normal gravitation at any height.
`normal_gravitational_potential`(height)	Normal gravitational potential at the given height above a sphere.
`normal_gravity`(latitude, height[, si_units])	Normal gravity of the sphere at the given latitude and height.
`normal_gravity_potential`(latitude, height)	Normal gravity potential of the sphere at the given latitude and height.

Attributes#

Sphere.area#: The area of the sphere. Definition: \(A = 4 \pi r^2\). Units: \(m^2\).

Sphere.area_equivalent_radius#: The area equivalent radius of the sphere is equal to its radius. Definition: \(R_2 = R\). Units: \(m\).

Sphere.eccentricity#: Alias for the first eccentricity.

Sphere.first_eccentricity#: The (first) eccentricity of the sphere is equal to zero. 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. Definition: \(f = \dfrac{a - b}{a}\). Units: adimensional.

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

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

Sphere.mean_radius#: The mean radius of the ellipsoid is equal to its radius. Definition: \(R_0 = R\). Units: \(m\).

Sphere.reference_normal_gravitational_potential#: The normal gravitational potential on the surface of the sphere. Definition: \(U_0 = \dfrac{GM}{R}\). Units: \(m^2 / s^2\).

Sphere.semiaxes_mean_radius#: The arithmetic mean radius of the ellipsoid semi-axes is equal to its radius. Definition: \(R_1 = R\). Units: \(m\).

Sphere.semimajor_axis#: The semimajor axis of the sphere is equal to its radius. Units: \(m\).

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

Sphere.semimedium_axis#: The semimedium axis of the sphere is equal to its radius. Units: \(m\).

Sphere.semiminor_axis#: The semiminor axis of the sphere is equal to its radius. Units: \(m\).

Sphere.thirdflattening#: The third flattening of the sphere is equal to zero. Definition: \(f^{\prime\prime}= \dfrac{a -b}{a + b}\). Units: adimensional.

Sphere.volume#: The volume of the sphere. Definition: \(V = \dfrac{4}{3} \pi r^3\). Units: \(m^3\).

Sphere.volume_equivalent_radius#: The volume equivalent radius of the sphere is equal to its radius. Definition: \(R_3 = R\). Units: \(m\).

Methods#

Sphere.centrifugal_potential(latitude, height)[source]#

Centrifugal potential at the given latitude and height above the sphere.

The centrifugal potential \(\Phi\) at latitude \(\theta\) and height above the sphere \(h\) is

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

in which \(R\) is the sphere radius and \(\omega\) is the angular velocity.

Parameters:

latitudefloat or array: The latitude where the centrifugal potential will be computed (in degrees).
heightfloat or array: The height above the sphere of the computation point (in meters).

Returns:

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

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:

heightfloat or array: The height above the surface of the sphere of the computation point (in meters).
si_unitsbool: Return the value in mGal (False, default) or m/s² (True)

Returns:

gammafloat 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_gravitational_potential(height)[source]#

Normal gravitational potential at the given height above a sphere.

Computes the normal gravitational potential generated by the sphere at the given height above the surface of the sphere \(h\):

\[V(h) = \dfrac{GM}{(R + h)}\]

in which \(R\) is the sphere radius and \(GM\) is the geocentric gravitational constant of the sphere.

Caution

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

Parameters:

heightfloat or array: The height above the surface of the sphere of the computation point (in meters).

Returns:

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

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

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

Parameters:

latitudefloat or array: The spherical latitude where the normal gravity will be computed (in degrees).
heightfloat or array: The height above the surface of the sphere of the computation point (in meters).
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

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, the gravity potential is not constant at the surface, and the normal gravity vector is not normal to the surface of the sphere.

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

Sphere.normal_gravity_potential(latitude, height)[source]#

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

Computes the normal gravity potential (gravitational + centrifugal) generated by the sphere at the given spherical latitude \(\theta\) and height above the surface of the sphere \(h\):

\[U(\theta, h) = V(h) + \Phi(\theta, h) = \dfrac{GM}{(R + h)} + \dfrac{1}{2} \omega^2 \left(R + h\right)^2 \cos^2(\theta)\]

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

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

Parameters:

latitudefloat or array: The spherical latitude where the normal gravity will be computed (in degrees).
heightfloat or array: The height above the surface of the sphere of the computation point (in meters).

Returns:

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

Notes

A sphere under rotation is not in hydrostatic equilibrium. Therefore, unlike the oblate ellipsoid, the gravity potential is not constant at the surface, and the normal gravity vector is not normal to the surface of the sphere.

boule.Sphere

Contents

boule.Sphere#

Attributes#

Methods#