Reference ellipsoids for geodesy and geophysics

Documentation (latest) • Documentation (main branch) • Contributing • Contact

Part of the Fatiando a Terra project

About

Boule is Python library for representing reference ellipsoids, calculating their gravity fields, and performing some global coordinate conversions. "Boule" is also French for "ball" as well as a traditional shape of bread resembling a squashed ball.

Some examples of where Boule can be applied:

• Storing and manipulating ellipsoid parameters for spherical harmonic analysis.
• Calculating normal gravity for generating gravity anomalies and disturbances.
• Modelling in spherical coordinates, which requires geodetic to geocentric spherical coordinate conversions.

Project goals

• Provide a representation of ellipsoid parameters and derived quantities, including units and citations.
• Convert between geodetic coordinates and geocentric spherical, topocentric, etc.
• Calculate the gravity, gravitational, and centrifugal potential (and its derivatives) of ellipsoids in closed form.
• Include a range ellipsoids for the Earth and other planetary bodies.

Project status

Boule is ready for use but still changing. This means that we sometimes break backwards compatibility as we try to improve the software based on user experience, new ideas, better design decisions, etc. Please keep that in mind before you update Boule to a newer version.

We welcome feedback and ideas! This is a great time to bring new ideas on how we can improve the project. Join the conversation or submit issues on GitHub.

Getting involved

🗨️ Contact us: Find out more about how to reach us at fatiando.org/contact.

👩🏾‍💻 Contributing to project development: Please read our Contributing Guide to see how you can help and give feedback.

🧑🏾‍🤝‍🧑🏼 Code of conduct: This project is released with a Code of Conduct. By participating in this project you agree to abide by its terms.

Imposter syndrome disclaimer: We want your help. No, really. There may be a little voice inside your head that is telling you that you're not ready, that you aren't skilled enough to contribute. We assure you that the little voice in your head is wrong. Most importantly, there are many valuable ways to contribute besides writing code.

This disclaimer was adapted from the MetPy project.

License

This is free software: you can redistribute it and/or modify it under the terms of the BSD 3-clause License. A copy of this license is provided in LICENSE.txt.

Issues

Add geocentric_radius to TriaxialEllipsoid

opened on 2023-01-16 09:57:55 by blazej-bucha

• Add the geocentric_radius method to the TriaxialEllipsoid class that computes the radius of surface points on triaxial ellipsoids.
• Add tests to check geocentric_radius of TriaxialEllipsoid.
• Running make format made few edits also to the previous code.

Please take a look at the PR to check if it makes sense.

Relevant issues/PRs: Fixes #105

Add geocentric surface radius calculation to TriaxialEllipsoid

opened on 2022-06-10 16:40:02 by leouieda

Description of the desired feature:

72 added a TriaxialEllipsoid class defining only the base geometric properties. In #47 @MarkWieczorek mentioned that calculating the surface radius of the ellipsoid would be useful. Seems like a good place to start adding some computations.

https://en.wikipedia.org/wiki/Ellipsoid is a good place to start with equations and references.

Are you willing to help implement and maintain this feature?

Willing to help if anyone wants to give this a shot but probably won't do it myself.

Add volume property to Sphere

opened on 2020-11-12 05:38:48 by dabiged

The proposed Triaxial Ellipsoid class has a volume method. For consistency a similar method should be created for the Sphere and (biaxial) ellipsoid classes too.

Mentioned by @santisoler in #72 .

Are you willing to help implement and maintain this feature? Yes/No

Use a unit package

opened on 2020-01-10 14:03:40 by leouieda

Tracking units through these computations is hard. For now, we settled on using SI for all inputs and most outputs. It would be better to use a unit package like Pint.

Releases

v0.4.1 2022-10-27 14:15:45

Released on: 2022/10/27

doi: https://doi.org/10.5281/zenodo.7258175

Documentation:

• Update contact link in the docs side bar (#141)
• Add definition of "co-located grids" to the glossary (#139)
• Fix typo in overview docs page (#137)

Maintenance:

• Undo deprecation of coordinate conversion methods (#142)
• Drop support for Python 3.6 (#144)
• Add serve target in doc/Makefile (#136)

This release contains contributions from:

• Mariana Gomez
• Santiago Soler
• Leonardo Uieda

v0.4.0 2022-08-08 13:45:18

Released on: 2022/08/09

doi: https://doi.org/10.5281/zenodo.6779998

WARNING: Boule v0.4.0 is the last release that is compatible with Python 3.6.

Backwards incompatible changes:

• Refactor the Sphere class to not inherit from Ellipsoid. Breaks backwards compatibility due to the removal of inherited methods and attributes (#129)
• Make all package modules private by adding a leading _ to their name (#119)
• Rename the Ellipsoid.emm attribute to Ellipsoid._emm to make it private (#123)
• Remove the boule.test function (#116)

Deprecations:

• Deprecate the coordinate conversion methods which have been ported to the pymap3d library v2.9.0 (#126)

New features:

• Add the volume property to Ellipsoid (#132)
• Add missing attributes to Ellipsoid for pymap3 compatibility (#121)
• Add the TriaxialEllipsoid class with geometric parameters (#72)
• Add a normal gravitation method to Sphere (#73)

Documentation:

• Add a logo for Boule (#125)
• Refactor the documentation tutorials to shift the focus to how to do things with Boule and point to other pages for more of the theory (#130)
• Refactor documentation of TriaxialEllipsoid (#128)
• Refactor the documentation of Ellipsoid (#127)
• Fix formatting for code to pip install from GitHub (#118)
• Fix license link and compatibility warning in the README (#117)
• Use jupyter-sphinx instead of sphinx-gallery and update the documentation front page (#112)
• Point to our organization wide guides in the documentation (#108)
• Add an example calculating global gravity disturbances (#102)
• Update Sphinx version to 4.5.0 (#103)

Maintenance:

• Convert the README to Markdown (#113)
• Specify oldest supported version of each dependency (#111)
• Move to pyproject.toml/setup.cfg with build instead of setup.py (#110)
• Replace pylint with flake8 and some extensions (#109)
• Rename the git \"master\" branch to \"main\" (#107)
• Update code style to Black 22.3.0 (#104)
• Replace Google Analytics with Plausible for page visit statistics (#99)

This release contains contributions from:

• Agustina Pesce
• Chris Dinneen
• Leonardo Uieda
• Santiago Soler

v0.3.1 2021-10-19 07:55:58

Released on: 2021/10/19

doi: https://doi.org/10.5281/zenodo.5577885

Bug fix:

• Package the missing requirements.txt file in source distributions (#96)

This release contains contributions from:

• Leonardo Uieda

v0.3.0 2021-10-18 14:19:22

Released on: 2021/10/18

doi: 10.5281/zenodo.5575827

Highlights:

• Add support for Python 3.9 and 3.10 (#87)
• Add reference Sphere class for bodies with zero flattening (#42)
• Add spheroids for Venus (#68), Mercury, and the Earth\'s Moon (#71)

Enhancements:

• Warn users if normal gravity is being computed on internal point (#83)
• Add option to return normal gravity in SI units (#69)
• Add parameter validation for the Sphere class (#56)
• Add parameter validation for the Ellipsoid class (#45)
• Make parameter validation methods private (#55)
• Tests normal gravity against Somigliana equation (#51)
• Fix normal gravity equation of Sphere (#52)
• Fix missing centrifugal term for spheres at the equator (#48)

Documentation:

• Update documentation theme to sphinx-book-theme (#92)
• Add tutorial for geodetic to geocentric coordinate transformations (#84)
• Improvements to docstrings of Ellipsoid and Sphere (#49)

Maintenance:

• Add Mariana Gomez to AUTHORS.md (#90)
• Add Chris Dinneen to AUTHORS.md (#74)
• Only run CI for Python 3.6 and 3.10 now that it\'s out (#89)
• Update setuptools_scm configuration to save a boule/_version.py file instead of relying on pkg_resources to get the version number (#91)
• Use the OSI version of item 3 in the license (#70)
• Add license and copyright notice to every .py file (#67)
• Refactor GitHub Actions workflows to separate building the docs (#65)
• Replace versioneer with setuptools-scm (#61)
• Remove configuration files for unused CI (#60)
• Replace Travis and Azure with GitHub Actions (#57)
• Add conda-forge badge to the README (#40)
• Format the doc/conf.py file with Black (#41)

This release contains contributions from:

• Leonardo Uieda
• Santiago Soler
• Chris Dinneen
• Mariana Gomez
• Hugo van Kemenade
• Lu Li

v0.2.0 2020-07-10 21:00:48

• Add the Ellipsoid.geocentric_radius method to calculate the distance from the center of the ellipsoid to its surface as a function of latitude (geodetic or geocentric). (#37)
• Add the Ellipsoid.prime_vertical_radius method for computing the prime vertical radius (usually represented by N in equations) as a function of geodetic latitude. (#35)
• Fix typo in README contributing section (#32)

This release contains contributions from:

• Leonardo Uieda
• Rowan Cockett
• Santiago Soler

v0.1.1 2020-01-10 14:17:24

This release contains only a documentation fix: include install instructions for conda and pip. No functionality has been changed (hence, no DOI was issued).