Overview

The main functionality of Boule is contained in the Ellipsoid class. It defines a Reference Ellipsoid: an oblate ellipsoid that approximates the shape of the Earth (or other planetary body). Ellipsoids are generally specified by 4 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\)): the multiplication of the total mass of the ellipsoid and the gravitational constant.

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

With these parameters, Boule can calculate gravity, coordinate conversions, and other derived physical and geometric properties of the ellipsoid.

The library

All functions and classes in Boule are available in 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 built-in ellipsoids that can be accessed as global variables in the boule module:

print(bl.WGS84)
print(bl.MARS)

Out:

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.')
Ellipsoid(name='MARS', semimajor_axis=3395428, flattening=0.005227617843759314, geocentric_grav_const=42828372000000.0, angular_velocity=7.0882181e-05, long_name='Mars Ellipsoid', reference='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), 1. doi:10.1007/s11038-009-9342-7')

As seen above, Ellipsoid instances can be printed to record their defining attributes. Additionally, ellipsoids define a name (short and long version) and reference for the origin of the numbers used:

print(bl.MARS.name)
print(bl.MARS.reference)

Out:

MARS
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), 1. doi:10.1007/s11038-009-9342-7

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

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

Out:

0.10211712735480878
3.731907392736793
3.7087546578837722

You can also define your own ellipsoid. For example, this would be the definition of a sphere with 1000 m radius and dummy values for \(GM\) and \(\omega\):

sphere = bl.Ellipsoid(
    name="Sphere",
    long_name="Ellipsoid with 0 flattening",
    flattening=0,
    semimajor_axis=1000,
    geocentric_grav_const=1,
    angular_velocity=1,
)
print(sphere)
print(sphere.semiminor_axis)
print(sphere.first_eccentricity)

Out:

Ellipsoid(name='Sphere', semimajor_axis=1000, flattening=0, geocentric_grav_const=1, angular_velocity=1, long_name='Ellipsoid with 0 flattening', reference=None)
1000
0.0

However, the equations for calculating gravity are not suited for the 0 flattening case. So don’t define reference spheres like this. This is due to the first eccentricity being 0 (it appears in divisions in the equations).

print(sphere.gravity_pole)

Out:

/home/travis/miniconda/envs/testing/lib/python3.7/site-packages/boule/ellipsoid.py:137: RuntimeWarning: divide by zero encountered in double_scalars
  ratio = self.semiminor_axis / self.linear_eccentricity
/home/travis/miniconda/envs/testing/lib/python3.7/site-packages/boule/ellipsoid.py:142: RuntimeWarning: invalid value encountered in double_scalars
  / (1.5 * ((1 + 3 * ratio ** 2) * arctan - 3 * ratio))
nan

Computations

Ellipsoids can be used for computations generally encountered in geodetic and geophysical applications:

1. Normal gravity

2. Converting geodetic latitude and height into geocentric latitude and radius.

See the respective tutorials and reference documentation for more information.