Skip to content

Add User Guide section on tesseroid layers - #695

Merged
santisoler merged 4 commits into
fatiando:mainfrom
manduinca:docs/tesseroid-layer-user-guide
Sep 9, 2026
Merged

santisoler merged 4 commits into
fatiando:mainfrom
manduinca:docs/tesseroid-layer-user-guide

Conversation

@manduinca

Copy link
Copy Markdown
Contributor

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!

Comment thread doc/user_guide/forward_modelling/tesseroid.rst Outdated
Comment thread doc/user_guide/forward_modelling/tesseroid.rst
@manduinca

Copy link
Copy Markdown
Contributor 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.

@santisoler
santisoler self-requested a review August 26, 2026 00:07
Shift the topography to only positive values so we don't have tesseroids
below the reference for this example. Add a plot of the topography next
to the plot of the surface.
@santisoler

Copy link
Copy Markdown
Member

Thanks for applying the changes @manduinca. I just took the liberty to push some small changes to the guide: I shifted the topography to positive values only, so we don't have tesseroids below the reference. In some situations, we usually assign negative density contrast to tesseroids that fall below the reference (when modelling gravity anomalies), but I didn't want to get into that for this particular example. But I also wanted the anomaly to look with a bit more variation.

I also added a plot of the topography next to the one for the surface, so readers can see the difference between them.

Let me know what do you think. After this I think this is ready to be merged.

@manduinca

Copy link
Copy Markdown
Contributor Author

Thanks @santisoler! The changes look great. Shifting the topography to positive values keeps the example simple (no need to get into negative density contrasts here), and plotting the topography next to the surface makes the difference between the two much clearer. From my side this is ready to be merged.

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

Thanks a lot @manduinca for addressing my comments. I'm merging this one (even the code-style fails due to the issue I'll fix in #699) 🚀

Congrats for the hard work, and sorry for my usual delays on replying!

@santisoler
santisoler merged commit b56a0b4 into fatiando:main Sep 9, 2026
13 of 14 checks passed
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