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`(coordinates)	Centrifugal potential of the rotating sphere.
`normal_gravitation`(coordinates[, si_units])	Normal gravitation of the sphere.
`normal_gravitational_potential`(coordinates)	Normal gravitational potential of the sphere.
`normal_gravity`(coordinates[, si_units])	Normal gravity of the sphere.
`normal_gravity_potential`(coordinates)	Normal gravity potential of the sphere.

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(coordinates)[source]#

Centrifugal potential of the rotating sphere.

Calculate the centrifugal potential due to the rotation of the sphere about its z-axis at the given points.

Parameters:

coordinatestuple = (longitude, latitude_spherical, height): Longitude, latitude, and height coordinates of the computation points in a geocentric spherical coordinate system. The height is measured from the surface of the sphere. 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 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.

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

Normal gravitation of the sphere.

Computes the magnitude of the gradient of the gravitational potential generated by the sphere at the points. Assumes a homogeneous internal density distribution for the sphere.

Caution

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

Parameters:

coordinatestuple = (longitude, latitude_spherical, height): Longitude, latitude, and height coordinates of the computation points in a geocentric spherical coordinate system. The height is measured from the surface of the sphere. 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 and latitude are not used in computations (the field is symmetric), they can be assigned None.
si_unitsbool: Return the value in mGal (False, default) or m/s² (True)

Returns:

gammafloat or array: The normal gravitation in mGal.

Notes

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.

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((None, None, 1))
>>> print(f"{g:.2f} mGal")
50000.00 mGal

Sphere.normal_gravitational_potential(coordinates)[source]#

Normal gravitational potential of the sphere.

Computes the normal gravitational potential generated by the sphere at the given points. Assumes a homogeneous internal density distribution for the sphere.

Caution

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

Parameters:

coordinatestuple = (longitude, latitude_spherical, height): Longitude, latitude, and height coordinates of the computation points in a geocentric spherical coordinate system. The height is measured from the surface of the sphere. 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 and latitude are not used in computations (the field is symmetric), they can be assigned None.

Returns:

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

Notes

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.

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

Normal gravity of the sphere.

Computes the magnitude of the gradient of the gravity potential generated by the sphere at the given points.

Note

Unlike the boule.Ellipsoid, the gravitational potential of the sphere assumes a homogeneous density distribution. There is no requirement that the gravity potential at the surface of the sphere be constant, like for the ellipsoid. This is because the ellipsoid equations have a singularity when the flattening tends to zero.

Caution

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

Parameters:

coordinatestuple = (longitude, latitude_spherical, height): Longitude, latitude, and height coordinates of the computation points in a geocentric spherical coordinate system. The height is measured from the surface of the sphere. 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

Computes the magnitude of the gradient of the gravity potential (gravitational + centrifugal) 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.

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((None, 0, 0))
>>> print(f"{gamma_equator:.2f} mGal")
175000.00 mGal
>>> gamma_pole = sphere.normal_gravity((None, 90, 0))
>>> print(f"{gamma_pole:.2f} mGal")
200000.00 mGal

Sphere.normal_gravity_potential(coordinates)[source]#

Normal gravity potential of the sphere.

Computes the normal gravity potential (gravitational + centrifugal) generated by the sphere at the given points. Assumes a homogeneous internal density distribution for the sphere.

Caution

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

Parameters:

coordinatestuple = (longitude, latitude_spherical, height): Longitude, latitude, and height coordinates of the computation points in a geocentric spherical coordinate system. The height is measured from the surface of the sphere. 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:

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

Notes

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.

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#