Docs update - #1103
Open
javoha wants to merge 16 commits into
Open
Conversation
…ctions Reorders examples/tutorials/ so sphinx-gallery's alphabetical folder sorting reflects the intended learning path: a_fundamentals (video tutorials), b_advanced (former ch1_fundamentals, led by get_started), c_specialized (former ch2-4 plus json_io).
Aligns model2-model7 example scripts with the API style used in the video tutorials: plain `geo_model` variable (no redundant type annotation or alias), `gp.set_is_fault()` instead of hand-built fault relation matrices, and consistent 2D/3D plotting sections across all six files. Also drops a dead ERODE reassignment that duplicated the default relation type. Verified via direct execution that set_is_fault() reproduces the same fault_relations matrices as the manual code it replaces, and that all six models still compute successfully end-to-end.
Strips the VTK export, mesh vertex/normal extraction, and Excel/XYZ conversion code out of the "simplest model" example so it's a plain baseline consistent with b02-g07 (geo_model var, same 2D/3D sections). The removed code covers a genuinely useful workflow but doesn't belong bolted onto the intro example; it's parked for a future dedicated export/post-processing tutorial.
Drops the redundant gp.data.GeoModel type annotation, renames geo_data to geo_model for consistency, removes the unused sol capture from compute_model, and standardizes the 3D plot call to show_lith=True, show_boundaries=True, ve=None. Model-selection logic and local data path are unchanged. Verified all 8 sub-models (1,2,3,5,6,7,8,9) still compute and plot correctly; the PyTorch-backend compute call itself fails locally due to a pre-existing torch/numpy ABI mismatch in this venv, unrelated to this refactor.
Applies the same syntax modernization used for the geometries examples to the six real case-study scripts (Alesmodel, Claudius, Greenstone, Hecho, Moureze, Perth_basin): drops redundant type annotations, converts set_is_fault() calls to the positional form, removes dead imports/env vars, and fixes two copy-paste project_name bugs (Alesmodel was 'Claudius', Hecho was 'Moureze'). Rewrites each file's docstring with a clear title, subtitle, and short geological description, and cleans up typos and unclear phrasing throughout the inline comments. Also tidies grammar and expands the terse text in the three examples/examples README.rst files. Verified by direct execution that all six models still compute end-to-end; Alesmodel and Perth_basin (both slow/unstable models per their own docs) were confirmed separately, including Perth_basin's topography 3D plots after upgrading pyvista (0.43.6 -> 0.48.4) fixed a pre-existing extract_surface() incompatibility unrelated to these edits.
Applies the same syntax modernization used elsewhere in the tutorials reorg to ch2_1_gravity, ch2_2_cell_selection, ch3_1_kriging_interpolation_and_simulation, and ch4-1-Topology: drops redundant type annotations, removes dead imports/variables, and fixes stray formatting. Fixes real doc bugs found along the way: ch2_2's explanation referenced a nonexistent function name and wrong attribute names (actual API is left_voxel_edges/right_voxel_edges, not kernel_dxyz_left/right); ch4-1-Topology cited a nonexistent gp.topology_compute instead of the real tp.compute_topology; ch2_1/ch2_2 linked to a pre-restructuring GitHub notebook path that no longer exists. Titles/subtitles for all four dropped the stale "Chapter N"/"N.M" numbering left over from the old folder structure. ch3_1 and ch4-1-Topology now carry a note that they depend on gempy_plugins, a separately maintained package, not core GemPy. Verified all four execute end-to-end after two unrelated stale-dependency fixes surfaced during verification: pyvista (0.43.6 -> 0.48.4, fixed a topography-plot crash) and gempy_plugins (2023.2.0b1 -> 2026.0.2, fixed a hard crash in the kriging tutorial from an OctreeLevel API mismatch). json_io/ tutorials are intentionally left untouched; they're not currently reachable from sphinx-gallery (a pre-existing subdirectory discovery gap) and should stay unfeatured for now.
Move ch1_4_onlap_relations.py, ch1_5_fault_relations.py, and ch1_3c_topography.py into b_advanced/_hidden/, a nested directory sphinx-gallery does not scan for subsections (confirmed via the existing json_io case). Onlap and fault relations are already covered by the video tutorials; topography stays its own tutorial, just unfeatured for now. History preserved via git mv, fully restorable later.
Full rewrite covering plot_2d's options in a clearer progression: model setup -> a single orthogonal section (cell_number/'mid'/position, show_topography) -> the same section as a scalar field (explaining series_n) and as contact-lines-only -> named sections and the geological map -> combining all of the above in one 2x2 figure -> vertical exaggeration -> overlaying custom data (three boreholes to different depths, both on an orthogonal cut and a named section). ch1_3b_cross_sections.py is fully absorbed into this and removed - its custom-section and topography content now lives here, modernized to the current gempy syntax and the canonical simple_fault_model used elsewhere in these tutorials.
Rewrites ch1_7_3d_visualization.py, replacing the old minimal GRABEN + LiquidEarth demo with a fuller tour of plot_3d: the full model, input data alone, the solid lithology volume versus the layer-boundary surfaces (show_lith vs show_boundaries), and a scalar field (active_scalar_field='sf_N', the 3D equivalent of the 2D tutorial's series_n). Keeps the graben model for its distinctive two-fault structure, now with an added random topography so show_topography has something to actually drape a geological map over. Finishes with boreholes overlaid in 3D via the returned GemPyToVista object's underlying PyVista Plotter (.p) - the same idea as overlaying a borehole on a 2D section, generalized to 3D tubes with sphere collars. Every plot_3d call, including this one, opens a real interactive PyVista view rather than a forced static screenshot, matching how every other 3D example in this codebase already calls plot_3d - docs/source/conf.py sets pyvista.OFF_SCREEN globally for the actual doc build, so this needs no special-casing here. LiquidEarth cloud-upload integration dropped (needs an account/token, not exercisable in this context). A VTK-export section (surfaces, input meshes, and the volume saved to .vtk, plus mesh vertex/normal extraction to Excel/XYZ) was drafted and verified working from a snippet stashed during an earlier cleanup, but cut at review.
Replaces the old low-level ch1_3a_grids.py (which instantiated a bare Grid()/RegularGrid() directly, bypassing gp.create_geomodel) with a tour built around the canonical simple_fault_model used throughout b_advanced. Structure: why grids/discretization exist at all (gempy can only evaluate its implicit potential-field function at a finite set of query points) -> regular grid vs octree grid, resolved from source and empirically: passing an explicit resolution always selects the dense grid outright (octree is unreachable at the same time by construction), while refinement independently controls how many octree levels get built for dual-contouring surface-mesh extraction in plot_3d - confirmed visually that refinement changes mesh smoothness with the lithology block held fixed. Also documents a real gotcha: refinement defaults to 1, but gempy silently floors that to 4 internally since fewer than 2 levels isn't usable for surface extraction, so most examples in this doc set that leave refinement at its default already get that floor, not a literal single level. Then custom grids (arbitrary XYZ query points, e.g. borehole locations, queryable via solutions.raw_arrays.custom after a recompute) and centered grids (kept from the old tutorial, now built against this model's extent, cross-referenced to ch2_2_cell_selection.py for the full gravity-kernel example instead of the old tutorial's dead GitHub notebook link), each with a 3D scatter plot showing what the grid's points actually look like. Finishes with a brief pointer to ch1_6_2d_visualization.py for topography/section grids, which are conceptually the same "grid type" mechanism but covered there in full.
…cope
Both tutorials used to duplicate a lot of the same technical ground
(data classes list, backend admonitions) while also each carrying
content that belonged more clearly to one or the other. Reworked with
a clear split: Basics is now the technical companion to the video
tutorials (deeper API/class detail on the same simple_fault_model),
Getting Started is trimmed to the workflow of building a model
incrementally from sparse cross-section data, with less API
reference.
Basics gains (moved from Getting Started, or new):
- element_id_name_map and fault_relations, both concrete technical
details not shown anywhere before
- manually constructing StructuralElement/StructuralGroup directly,
as a standalone demo (moved from Getting Started, where it's still
used but no longer re-explained)
- dc_meshes (mesh vertices/edges) and input_transform.apply_inverse
- save_model/load_model, replacing a stale admonition claiming no
serialization exists ("use pickle") - it does now, confirmed
working end-to-end including the round-trip
- set_is_fault fixed to the positional style used everywhere else in
this doc set; dropped a stale "numpy or tensorflow backend"
admonition (gempy_engine only ever had numpy and pytorch)
Getting Started keeps the workflow narrative that makes it worth
having as a separate tutorial: reading surface points off a borehole
cross-section image, the minimum-data-for-computation rule, and the
full erode/onlap/fault progression on the same discontinuity data
(unchanged, per an earlier decision). Topography is kept too, since
it makes the finished model feel more complete rather than a bare
academic exercise. Dropped: the duplicated data-classes list, a
DEFAULT_BACKEND=PYTORCH env var with no actual effect on anything the
tutorial demonstrates, and a closing "Extracting Model Solutions"
section that's now redundant with Basics (dc_meshes) and the Grids
tutorial (lith_block/grid values).
Also fixed a real crash found while verifying this end-to-end:
plot_2d(section_names=['topography'], show_topography=True) hit the
same pre-existing geological_map indexing bug already known from
gempy_viewer (show_boundaries defaults True and breaks for the
topography section specifically) - added show_boundaries=False.
Both folders used the same ad-hoc "chN_M" chapter-numbering scheme
this whole restructuring project has been moving away from, and in
both cases the numbers no longer matched the intended reading order:
- b_advanced: ch1_0_get_started sorted before ch1_1_basics, but
Basics is meant to come first (it's the technical companion to the
video tutorials; Cross-Section builds on concepts it introduces).
- c_specialized: ch2_1_gravity sorted before ch2_2_cell_selection, but
gravity.py's own text says "see the Centered Grids for Geophysics
tutorial for background" - a forward reference to content the
reader hadn't gotten to yet.
Renamed both folders to the letter+2-digit scheme already proven in
examples/examples/geometries/ (a01, b02, c03...), giving the whole
examples/ tree one consistent naming convention instead of three:
b_advanced/ c_specialized/
a01_basics.py a01_cell_selection.py
b02_cross_section.py b02_gravity.py
c03_grids.py c03_kriging.py
d04_2d_visualization.py d04_topology.py
e05_3d_visualization.py
Updated the two real (non-auto-generated) cross-references this
affected: two :doc: links in c03_grids.py, and docs/source/conf.py's
commented-out ignore_pattern. Also updated the filename token in
docs/source/index.rst's hardcoded 3D-view thumbnail link - the exact
figure number in that link (_009) is a guess carried over from the
old file and hasn't been verified against a real sphinx-gallery
build, since a01_basics.py's rewritten content has a different
sequence of plots than the original ch1_1_basics.py did. Left
b_advanced/_hidden/ and c_specialized/json_io/ untouched - neither is
scanned by sphinx-gallery, so renaming them serves no ordering
purpose.
b_advanced and c_specialized both itemized specific tutorial topics (e.g. "onlap and fault relations" for b_advanced, now hidden content; a fixed list of four specific c_specialized topics) that go stale every time a tutorial is added, removed, or reworked - a_fundamentals already avoided this. Trimmed both to a short, generic description of the section's purpose instead, so future additions don't require editing these files. Kept c_specialized's probabilistic-vs-classical- inversion note, condensed, since it's a durable statement about GemPy's design rather than a list of current content. Also fixed a small grammar slip in the top-level tutorials/README.rst. json_io/README.rst intentionally left untouched, per the standing instruction not to touch that directory without being asked.
- Move examples/examples/real/mik.py to _hidden/ since it's broken against the currently installed subsurface API and not fixable via a simple dependency bump. - Fix show_boundaries=False on gpv.plot_2d(section_names=['topography']) calls in Alesmodel.py and _hidden/ch1_3c_topography.py to avoid the IndexError crash in the geological map drawing path.
- Rename tutorials/a_fundamentals -> a_getting_started, b_advanced -> b_fundamentals, c_specialized -> c_advanced, so folder names and displayed section titles line up: Getting Started -> Fundamentals -> Advanced, and update README titles/text and the one cross-folder :doc: reference accordingly. - Give the b_fundamentals (formerly b_advanced) tutorials more descriptive thumbnail titles, and point c03_grids.py and b02_cross_section.py's thumbnails at more representative figures (centered grid, final faulted cross-section). - Rename examples/examples/geometries/h08_more_examples.py's title to "Set of more complex examples", and fix the two real case-study titles (Claudius, Hecho) that didn't follow the Name/Region/Country pattern used by the others.
Contributor
Graphite Automations"Add gempy label" took an action on this PR • (07/29/26)1 label was added to this PR based on Miguel de la Varga's automation. |
- Make the Advanced section's README generic (plugins / specific workflows) rather than tied to a particular probabilistic-modeling framing, so new tutorials fit without rewriting it. - Rename c03_kriging.py's title to "Kriging and Simulating Properties" to distinguish it clearly from GemPy's own underlying geostatistics.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Restructure and modernize the tutorials and examples
The examples and tutorials had grown organically over several years, so a lot of it used inconsistent naming, snytax, or was hard to follow without already knowing GemPy. This PR cleans that up to make the docs a better on-ramp for new users.
What changed:
visualization) → Advanced (specific features like gravity, kriging, topology, custom cell selection).