Defining custom ellipsoids#

Boule comes with a range of built-in ellipsoids already but you may want to define your own. If that’s the case, then you have the following options to choose from:

Oblate ellipsoid

Class: boule.Ellipsoid

When to use: Your model has 2 semi-axis and non-zero flattening.

Caveat: Assumes constant gravity potential on its surface and has no specified density distribution.

Example

Sphere

Class: boule.Sphere

When to use: Your model has zero flattening.

Caveat: Definition of normal gravity is slightly different since it’s not possible for a rotating sphere to have constant gravity potential on its surface.

Example

Triaxial ellipsoid

Class: boule.TriaxialEllipsoid

When to use: Your model has 3 distinct semi-axis.

Caveat: Definition of normal gravity is the same as the case for the sphere. Gravity calculations are not yet available.

Example

Oblate ellipsoids#

Oblate ellipsoids are defined by 4 numerical parameters:

  1. The semi-major axis (\(a\)): the equatorial radius.

  2. The flattening (\(f = (a - b)/a\)): the ratio between the equatorial and polar radii.

  3. The geocentric gravitational constant (\(GM\)).

  4. The angular velocity (\(\omega\)): spin rate of the ellipsoid which defines the centrifugal potential.

You can also include metadata about where the defining parameters came from (a citation) and a long descriptive name for the ellipsoid. For example, this is how the WGS84 ellipsoid can be defined with boule.Ellipsoid using parameters from [HofmannWellenhofMoritz2006]:

import boule as bl


WGS84 = bl.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, B., & Moritz, H. (2006). Physical Geodesy "
        "(2nd, corr. ed. 2006 edition ed.). Wien ; New York: Springer."
    ),
)
print(WGS84)

Ellipsoid(name='WGS84', semimajor_axis=6378137, flattening=0.0033528106647474805, geocentric_grav_const=398600441800000.0, angular_velocity=7.292115e-05, long_name='World Geodetic System 1984', reference='Hofmann-Wellenhof, B., & Moritz, H. (2006). Physical Geodesy (2nd, corr. ed. 2006 edition ed.). Wien\u202f; New York: Springer.')

Warning

You must use boule.Sphere to represent ellipsoids with zero flattening. This is because normal gravity calculations in boule.Ellipsoid make assumptions that fail for the case of flattening=0 (mainly that the gravity potential is constant on the surface of the ellipsoid).

Spheres#

Spheres are defined by 3 numerical parameters:

  1. The radius (\(R\)).

  2. The geocentric gravitational constant (\(GM\)).

  3. The angular velocity (\(\omega\)): spin rate of the sphere which defines the centrifugal potential.

As with oblate ellipsoids, boule.Sphere also takes the same metadata as input. For example, here is the definition of the Mercury spheroid from parameters found in [Wieczorek2015]:

MERCURY = bl.Sphere(
    name="MERCURY",
    long_name="Mercury Spheroid",
    radius=2_439_372,
    geocentric_grav_const=22.031839221e12,
    angular_velocity=1.2400172589e-6,
    reference=(
        "Wieczorek, MA (2015). 10.05 - Gravity and Topography of the Terrestrial "
        "Planets, Treatise of Geophysics (Second Edition); Elsevier. "
        "doi:10.1016/B978-0-444-53802-4.00169-X"
    ),
)
print(MERCURY)

Sphere(name='MERCURY', radius=2439372, geocentric_grav_const=22031839221000.0, angular_velocity=1.2400172589e-06, long_name='Mercury Spheroid', reference='Wieczorek, MA (2015). 10.05 - Gravity and Topography of the Terrestrial Planets, Treatise of Geophysics (Second Edition); Elsevier. doi:10.1016/B978-0-444-53802-4.00169-X')

Triaxial ellipsoids#

Triaxial ellipsoids are defined by 5 numerical parameters:

  1. The semi-major axis (\(a\)): the largest radius.

  2. The semi-medium axis (\(b\)): the middle radius.

  3. The semi-minor axis (\(c\)): the smallest radius.

  4. The geocentric gravitational constant (\(GM\)).

  5. The angular velocity (\(\omega\)): spin rate of the ellipsoid which defines the centrifugal potential.

boule.TriaxialEllipsoid also takes the same metadata attributes as input. For example, here is the definition of the Vesta ellipsoid using parameters from [Russell2012]:

VESTA = bl.TriaxialEllipsoid(
    name="VESTA",
    long_name="Vesta Triaxial Ellipsoid",
    semimajor_axis=286_300,
    semimedium_axis=278_600,
    semiminor_axis=223_200,
    geocentric_grav_const=1.729094e10,
    angular_velocity=326.71050958367e-6,
    reference=(
        "Russell, C. T., Raymond, C. A., Coradini, A., McSween, H. Y., Zuber, "
        "M. T., Nathues, A., et al. (2012). Dawn at Vesta: Testing the "
        "Protoplanetary Paradigm. Science. doi:10.1126/science.1219381"
    ),
)
print(VESTA)

TriaxialEllipsoid(name='VESTA', semimajor_axis=286300, semimedium_axis=278600, semiminor_axis=223200, geocentric_grav_const=17290940000.0, angular_velocity=0.00032671050958367, long_name='Vesta Triaxial Ellipsoid', reference='Russell, C. T., Raymond, C. A., Coradini, A., McSween, H. Y., Zuber, M. T., Nathues, A., et al. (2012). Dawn at Vesta: Testing the Protoplanetary Paradigm. Science. doi:10.1126/science.1219381')

Attention

Gravity calculations have not been implemented yet for triaxial ellipsoids. If you’re interested in this feature or would like to help implement it, please get in touch.