Overview#

The library#

All functions and classes in Boule are available from the base namespace of the boule package. This means that you can access all of them with a single import:

# Boule is usually imported as bl
import boule as bl

Ellipsoids#

Boule comes with several built-in ellipsoids that are available as global variables in the boule module. The ellipsoids can be printed to view their defining attributes:

print(bl.WGS84)
print(bl.Moon2015)
print(bl.Vesta2017)

WGS84 - World Geodetic System (1984)
Oblate ellipsoid:
  • Semimajor axis: 6378137 m
  • Flattening: 0.0033528106647474805
  • GM: 398600441800000.0 m³/s²
  • Angular velocity: 7.292115e-05 rad/s
Source:
  Hofmann-Wellenhof, B., & Moritz, H. (2006). Physical Geodesy (2nd,
    corr. ed. 2006 edition ed.). Wien; New York: Springer.
Moon2015 - Moon spheroid (2015)
Spheroid:
  • Radius: 1737151 m
  • GM: 4902800070000.0 m³/s²
  • Angular velocity: 2.6617073e-06 rad/s
Source:
  Wieczorek, MA (2015). 10.05 - Gravity and Topography of the
    Terrestrial Planets, Treatise of Geophysics (Second Edition);
    Elsevier. https://doi.org/10.1016/B978-0-444-53802-4.00169-X
Vesta2017 - Vesta reference ellipsoid (2017)
Oblate ellipsoid:
  • Semimajor axis: 278556 m
  • Flattening: 0.17459684946653456
  • GM: 17288000000.0 m³/s²
  • Angular velocity: 0.0003267 rad/s
Source:
  Karimi, R., Azmoudeh Ardalan, A., & Vasheghani Farahani, S. (2017).
    The size, shape and orientation of the asteroid Vesta based on data
    from the Dawn mission. Earth and Planetary Science Letters, 475,
    71–82. https://doi.org/10.1016/j.epsl.2017.07.033
Comments:
  Geocentric biaxial ellipsoid

Ellipsoids define a name (short and long version) and reference for the origin of the numbers used:

print(f"{bl.Mars2009.name}: {bl.Mars2009.long_name}")
print(bl.Mars2009.reference)

Mars2009: Mars ellipsoid (2009)
Ardalan, A. A., Karimi, R., & Grafarend, E. W. (2009). A New Reference Equipotential Surface, and Reference Ellipsoid for the Planet Mars. Earth, Moon, and Planets, 106, 1-13. https://doi.org/10.1007/s11038-009-9342-7

Other derived properties of ellipsoids are calculated on demand when accessed:

print(bl.GRS80.first_eccentricity)
print(bl.GRS80.gravity_pole)
print(bl.GRS80.gravity_equator)

08181919104281579
832186368517242
78032677153605

Hint

You may have noticed that there are 3 different types of ellipsoids: Ellipsoid, Sphere, and TriaxialEllipsoid. They each offer different attributes and capabilities. Be sure to check out the List of functions and classes (API) for a full list of what each class offers.

Normal gravity#

Ellipsoids can be used for computations generally encountered in geodetic and geophysical applications. A common one is calculating normal gravity. Here is an example of using Boule to calculate the normal gravity of the WGS84 ellipsoid on the Earth’s surface (topography in the continents, the geoid in the oceans).

First, we need to import a few other packages:

import ensaio        # For downloading sample data
import pygmt         # For plotting maps
import xarray as xr  # For manipulating grids

Now we can download and open co-located grids of topography and geoid using ensaio and xarray:

The computation height can be defined by combining topography and geoid:

height = xr.where(
    topography >= 0,
    topography + geoid,  # geometric height of topography in the continents
    geoid,  # geoid height in the oceans
)

Finally, we can calculate normal gravity using normal_gravity at the given heights and plot it on a map with pygmt:

gamma = bl.WGS84.normal_gravity(topography.latitude, height)

fig = pygmt.Figure()
fig.grdimage(gamma, projection="W20c", cmap="viridis", shading="+a45+nt0.3")
fig.basemap(frame=["af", "WEsn"])
fig.colorbar(position="JCB+w10c", frame=["af", 'y+l"mGal"'])
fig.show()

Overview

Contents

Overview#

The library#

Ellipsoids#

Normal gravity#