.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "tutorials/overview.py" .. LINE NUMBERS ARE GIVEN BELOW. .. only:: html .. note:: :class: sphx-glr-download-link-note Click :ref:`here ` to download the full example code .. rst-class:: sphx-glr-example-title .. _sphx_glr_tutorials_overview.py: .. _overview: Overview ======== The main functionality of Boule is contained in the :class:`~boule.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 (:math:`a`): the equatorial radius. 2. The flattening (:math:`f = (a - b)/a`): the ratio between the equatorial and polar radii. 3. The geocentric gravitational constant (:math:`GM`): the multiplication of the total mass of the ellipsoid and the `gravitational constant `__. 4. The angular velocity (:math:`\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 :mod:`boule` package. This means that you can access all of them with a single import: .. GENERATED FROM PYTHON SOURCE LINES 40-44 .. code-block:: default # Boule is usually imported as bl import boule as bl .. GENERATED FROM PYTHON SOURCE LINES 45-50 Ellipsoids ---------- Boule comes with :ref:`built-in ellipsoids ` that can be accessed as global variables in the :mod:`boule` module: .. GENERATED FROM PYTHON SOURCE LINES 50-54 .. code-block:: default print(bl.WGS84) print(bl.MARS) .. rst-class:: sphx-glr-script-out Out: .. code-block:: none 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') .. GENERATED FROM PYTHON SOURCE LINES 55-58 As seen above, :class:`~boule.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: .. GENERATED FROM PYTHON SOURCE LINES 58-62 .. code-block:: default print(bl.MARS.name) print(bl.MARS.reference) .. rst-class:: sphx-glr-script-out Out: .. code-block:: none 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 .. GENERATED FROM PYTHON SOURCE LINES 63-65 Other derived properties of ellipsoids are calculated on demand when accessed: .. GENERATED FROM PYTHON SOURCE LINES 65-70 .. code-block:: default print(bl.MARS.first_eccentricity) print(bl.MARS.gravity_pole) print(bl.MARS.gravity_equator) .. rst-class:: sphx-glr-script-out Out: .. code-block:: none 0.10211712735480878 3.731907392736793 3.7087546578837722 .. GENERATED FROM PYTHON SOURCE LINES 71-74 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 :math:`GM` and :math:`\omega`: .. GENERATED FROM PYTHON SOURCE LINES 74-88 .. code-block:: default 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) .. rst-class:: sphx-glr-script-out Out: .. code-block:: none 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 .. GENERATED FROM PYTHON SOURCE LINES 89-92 If the ellipsoid has zero flattening (a sphere), you must use the :class:`boule.Sphere` class instead. For example, this would be the definition of a sphere with 1000 m radius and dummy values for :math:`GM` and :math:`\omega`: .. GENERATED FROM PYTHON SOURCE LINES 92-102 .. code-block:: default sphere = bl.Sphere( name="Sphere", long_name="Ellipsoid with 0 flattening", radius=1000, geocentric_grav_const=1, angular_velocity=1, ) print(sphere) .. rst-class:: sphx-glr-script-out Out: .. code-block:: none Sphere(name='Sphere', radius=1000, geocentric_grav_const=1, angular_velocity=1, long_name='Ellipsoid with 0 flattening', reference=None) .. GENERATED FROM PYTHON SOURCE LINES 103-115 Computations ------------ Ellipsoids can be used for computations generally encountered in geodetic and geophysical applications: 1. :ref:`Normal gravity ` 2. :ref:`Converting geodetic latitude and height into geocentric latitude and radius `. See the respective tutorials and :ref:`reference documentation ` for more information. .. rst-class:: sphx-glr-timing **Total running time of the script:** ( 0 minutes 0.004 seconds) .. _sphx_glr_download_tutorials_overview.py: .. only :: html .. container:: sphx-glr-footer :class: sphx-glr-footer-example .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: overview.py ` .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: overview.ipynb ` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_