Skip to content

Add User Guide section on tesseroid layers - #695

Open
manduinca wants to merge 2 commits into
fatiando:mainfrom
manduinca:docs/tesseroid-layer-user-guide
Open

Add User Guide section on tesseroid layers#695
manduinca wants to merge 2 commits into
fatiando:mainfrom
manduinca:docs/tesseroid-layer-user-guide

Conversation

@manduinca

Copy link
Copy Markdown

Closes #352

Adds a "Tesseroid layer" section to the tesseroid User Guide page, following the same structure as the prism layer section in prism.rst. It documents tesseroid_layer, the DatasetAccessorTesseroidLayer accessor and its .gravity() method, with a self-contained runnable example over a region in South America.

I kept it as a section inside tesseroid.rst (with a _tesseroid_layer label) rather than a new page, since the prism layer is documented the same way and #352 links to that anchor. No changes to the toctree for the same reason.

The one thing I made sure to highlight in an .. important:: note is the difference from the prism layer: surface and reference must be given as geocentric radii, not heights, so the example uses boule.geocentric_radius to build them.

I ran the example locally and it produces a sensible g_z field. I couldn't build the full HTML docs on my machine (no GMT binary for the PyGMT figure), so I'd appreciate a check that the plot cell renders on CI.

@santisoler

Copy link
Copy Markdown
Member

Thanks @manduinca for opening this PR! I'll go through it and leave a review soon!

@santisoler
santisoler self-requested a review July 22, 2026 16:18

@santisoler santisoler left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks really good @manduinca! Thanks a lot for taking the effort on writing it!

I left two minor suggestions below. Let me know what do you think.

I see that the style check on GitHub Actions are failing, but this is not your fault. I'm fixing it in #699. So don't worry about that!

Unlike the :func:`harmonica.prism_layer`, the ``surface`` and ``reference`` boundaries
of a tesseroid layer must be given as **radii** measured from the center of the Earth,
not as heights above a reference level.
We can use the :meth:`boule.geocentric_radius` method from :mod:`boule` to

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor fix to the reference to Boule's method:

Suggested change
We can use the :meth:`boule.geocentric_radius` method from :mod:`boule` to
We can use the :meth:`boule.Ellipsoid.geocentric_radius` method from :mod:`boule` to

import numpy as np

topography = 3e3 * np.sin(longitude * np.pi / 20) * np.cos(latitude * np.pi / 20)
surface = reference + topography

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it would be nice to add a plot after this cell with the surface, so readers can see the synthetic topography within the area and also its values, so it might stick better that those are radii and not oscillations around the ellipsoid.

@manduinca

Copy link
Copy Markdown
Author

Thanks for the review @santisoler! I applied your suggestion for the Boule reference and added a plot of the surface right after that cell. The colorbar ends up showing values around 6.37 million meters, so hopefully it's now much clearer that these are radii and not heights. The change of the ellipsoid radius with latitude is also visible in the plot, which I think helps drive the point home. Happy to tweak it if you had something else in mind.

By the way, I just opened #700 with the spherical terrain correction example for the User Guide (#353), which builds on this section. There's a design question in there about how to handle observation points that fall inside the tesseroids, whenever you get a chance.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Include an example on how to use tesseroid layers in the User Guide

2 participants