# 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 a definition of an ellipsoid with 1000 m semimajor axis, flattening equal to 0.5 and dummy values for $$GM$$ and $$\omega$$:

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


Out:

Ellipsoid(name='Ellipsoid', semimajor_axis=1000, flattening=0.5, geocentric_grav_const=1, angular_velocity=1, long_name='Ellipsoid with 0.5 flattening', reference=None)
500.0
0.8660254037844386


If the ellipsoid has zero flattening (a sphere), you must use the boule.Sphere class instead. For example, this would be the definition of a sphere with 1000 m radius and dummy values for $$GM$$ and $$\omega$$:

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


Out:

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


## Computations¶

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