Repository navigation
Overhaul the PhysicsNeMo-Mesh documentation and tutorials - #2122
Merged
Merged
Conversation
Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
…to 4-6 Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
@Tensorclass copies about 360 TensorDict methods onto Mesh, DomainMesh, BVH, and ClusterTree, so their API pages listed them all (core.html was 1.1 MB) and repeated TensorDict docstrings whose references do not resolve here. Skip members that come from tensordict, keeping dataclass fields. Also separate the list in the physicsnemo.mesh.spatial docstring from its lead-in, which docutils reported as unexpected indentation. Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Replace the narrative on index.rst, which repeats the User Guide's concepts chapter, with a short introduction, a CPU quick start, a map of the submodules, the new tutorial sequence, and toctrees grouped by task. Drop the claim that normals work on tetrahedral meshes in 3D (C15): normals need codimension 1. Add fields.rst for physicsnemo.mesh.fields (RankSpec, FieldSchema) and the MeshFieldAssociation names. Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
primitives.rst lists every primitive by family with its manifold and spatial dimensions, and documents each load function. core.rst follows the page template: the five fields, the tensorclass and TensorDict API, an example that runs, a summary of Mesh methods by task, and a DomainMesh example. Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Fix the Laplacian sign (C4), drop the nonexistent weight_power argument from compute_point_derivatives (C1), state that the LSQ vector identities hold only approximately (C2), and re-derive the dimension support table from main (C3). Add a setup block so every example runs in order, and document DEC divergence and integration. Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
geometry.rst passed a Mesh to compute_circumcenters, which takes the cell vertex coordinates, and treated the tuple from compute_cotan_weights_fem as one tensor. visualization.rst said matplotlib is the default in non-interactive environments; the automatic backend depends only on the spatial dimension. Both pages now follow the page template and document every public function. Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Fix the DEC divergence exactness claim (C5), the pad_to_next_power cell count (C6), the compute_point_normals default (C7), the dtype of Adjacency.indices (C8), the polyline_2d wavelength (C9), and how draw colors cells when point_scalars are active (C11). Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Apply the page template, add the boundaries_facets and neighbors_adjacency figures, and list each function in the reference. These packages have no __all__, so their automodule directives documented no functions. Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
List the real draw() defaults and the backend_options parameter (C10), describe how cells are colored when point_scalars are active (C11), and make every example run in order. Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Make the example define its mesh and check its stated values, add the calculus_lsq_vs_dec figure and notes on choosing a method, and list every derivative, integration, and measure function in the reference. Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Replace the removed physicsnemo.mesh.examples module with physicsnemo.mesh.primitives, fix the noise import path, and add lumpy_ball and the text module. Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Reorganize the old operations tutorial for readers who finished tutorials 1-3: explain why each operation matters, show how transform_point_data rotates vector fields with the geometry, compare subdivision schemes side by side, and use DomainMesh for meshes of different manifold dimensions. Move the topology checks to tutorial 7. Correct the merge requirements (point, cell, and global data keys) and the wireframe example (all edges, not the boundary of the boundary). Draw 3D figures with PyVista static images. Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Apply the page template, add the subdivision_schemes figure, check each stated value against the code, and list each function in the reference. Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Apply the page template, add the sampling_interpolation figure, make the repair example define its mesh, and list each function in the reference. Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
The example read a placeholder geometry.stl. It now builds a PyVista sphere, and the page documents from_zarr and to_zarr, which the automodule directive did not list. Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Describe ClusterTree and its plan types, use a closed sphere in the signed distance example, and add the summary table. Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Fix the calculus example's undefined key (C13), give every example the names it uses, and correct the printed outputs, the curvature captions, and the point-normal weighting. Add the User Guide and API reference links, the tutorial sequence, and the fields, DomainMesh, generation, integration, Zarr, and signed-distance features. Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
…s README Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
… pages Fix the refit example in generate.rst, which projected the inner boundary of the shell onto the outer sphere, and let it run on a CPU. Document partition_cells and CellPartition, and list each function in the reference. Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
The volume-and-bending example used a 2D square as a closed 3D surface, and the shrinkwrap examples used undefined meshes. Add a table of the transformation, deformation, and projection functions, a projections example, and explicit reference entries for the projections, whose automodule directive documented nothing. Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
…ADME Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
…t colors true and files smaller Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
…ure figures Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
….5 MB to 9.5 MB) Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
…e final figures Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
fields_rank_transforms: give the velocity arrows readable shafts, and draw the stress ellipses only at interior vertices so they stay inside the mesh. primitives_gallery: cut a full quarter out of both volumes, with the cut faces in a lighter tint, so the cut shows at doc width. Update the caption. shrinkwrap_solid_surface: add the Mesh[...] line from mesh_label to every panel title. Re-execute tutorial 3, which embeds the gallery. Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
…its parent cell's measure Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
…utorial 3 meshes 3 more cells, tutorial 5 total curvature changes in the 4th decimal) Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com> # Conflicts: # CHANGELOG.md
Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Use active voice, title case for dropdown titles, for each in place of per, and a numeral for 60 degrees. Fix the Mobius spelling and two readability issues in alt text and prose. No technical content changes. Signed-off-by: meg miranda <mmiranda@nvidia.com>
…puts only; tutorial 7 edge-length spread follows NVIDIA#2127) Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
…le prints them Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
…87738e) Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Use active voice, title case for dropdown titles and tab labels, commas in four-digit numbers, and for each in place of per. Capitalize the remeshing benchmark list, link the Bookstein reference title to its DOI, and fix five readability issues. No technical content changes. Signed-off-by: meg miranda <mmiranda@nvidia.com>
…lic/pr/mesh-docs-overhaul (6e057f9) Signed-off-by: Peter Sharpe <peterdsharpe@gmail.com>
Use active voice, add subjects to two fragments, title-case the three details summaries, hyphenate piecewise-linear, use en dashes in two ranges, and drop the redundant discrete before DEC. No technical content changes. Signed-off-by: meg miranda <mmiranda@nvidia.com>
Style fixes to the main, primitives, and visualization READMEs, and to the PhysicsNeMo-Mesh entries in the 2.3.0 changelog section. Signed-off-by: meg miranda <mmiranda@nvidia.com>
megnvidia
approved these changes
Oct 21, 2026
Collaborator
Author
|
/ok to test 3bfa4d6 |
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
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.
The Mesh User Guide on docs.nvidia.com lives in the internal physicsnemo-docs repository, so its half of this overhaul is a companion merge request there.
Summary
This PR overhauls the PhysicsNeMo-Mesh documentation: the API reference, the nine tutorial notebooks, and the module READMEs. Every page now opens with a picture, drawn from 26 new figures and 25 card thumbnails that committed scripts generate. The PR adds API pages for
physicsnemo.mesh.fieldsandphysicsnemo.mesh.primitivesand fixes the 15 documentation errors from the October 2 correctness audit. Every Python example in these docs now runs: 98 of 98, against 52 of 94 onmain.What changed
docs/api/mesh/: all 22 pages share one layout, with a figure, badges, and cards for the most used calls on the first screen. The index is a card grid of the submodules and a learning path through the tutorials.fields.rstandprimitives.rstare new. Eleven pages that showed no functions now list them, because their packages have no__all__.Mesh[1, n]is a graph with node positions, andto_edge_graph()andto_dual_graph()turn any mesh into one. The neighbors page, the module README, and tutorials 6 and 9 show edge features, message passing withindex_add_, and batching withMesh.merge.docs/img/mesh/: 26 new figures and 25 thumbnails, plus 15 older figures restyled. All of them share one style module,_style.py.examples/minimal/mesh/: nine notebooks in a new order, from a first mesh to ML pipelines. Each opens with a picture, and all were executed on a GB300 node.docs/conf.pyhides the roughly 360 TensorDict methods that@tensorclasscopies ontoMesh. Withoutsphinx-designinstalled, cards and tabs render as plain blocks.physicsnemo/. No library code changes.Results
These numbers compare
mainwith this PR. The examples were run in order by a script, and the warnings come from the published site build.mainCaveats
FieldSchema. The README says to install frommainuntil 2.3.0 is released.docs/img/mesh/. The notebooks embed some of them and total 9.4 MB, the same as onmain.Tests
A script ran every Python block of the API pages and READMEs in order, and all pass. All nine notebooks ran top to bottom on a GB300 node. The published site builds with 6 warnings on mesh pages, and a build without
sphinx-designalso succeeds.Checklist
Dependencies
None. The companion User Guide merge request in physicsnemo-docs depends on this PR.
Review Process
All PRs are reviewed by the PhysicsNeMo team before merging.
Depending on which files are changed, GitHub may automatically assign a maintainer for review.
We are also testing AI-based code review tools (e.g., Greptile), which may add automated comments with a confidence score. This score reflects the AI’s assessment of merge readiness and is not a qualitative judgment of your work, nor is it an indication that the PR will be accepted / rejected.
AI-generated feedback should be reviewed critically for usefulness. You are not required to respond to every AI comment, but they are intended to help both authors and reviewers. Please react to Greptile comments with 👍 or 👎 to provide feedback on their accuracy.