# 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.