PhysicsNeMo-Mesh Tutorials#

This directory contains a series of progressive tutorials introducing PhysicsNeMo-Mesh - NVIDIA’s GPU-accelerated mesh processing library for physics-AI applications.

What is PhysicsNeMo-Mesh?#

PhysicsNeMo-Mesh is a PyTorch-based library for working with simplicial meshes (point clouds, curves, surfaces, volumes) in a unified, dimensionally-generic framework. Key features include:

  • GPU-Accelerated: All operations vectorized with PyTorch, run natively on CUDA

  • Dimensionally Generic: Works with n-D manifolds embedded in m-D spaces

  • TensorDict Integration: Structured data management with automatic device handling

  • Differentiable: Seamless integration with PyTorch autograd

  • Flexible Data: Arbitrary-rank tensor fields on points, cells, or globally

For the complete feature list, see the physicsnemo.mesh README.

Prerequisites#

  • Python 3.10+

  • PyTorch 2.0+

  • CUDA-capable GPU (recommended, not required)

Installation#

pip install nvidia-physicsnemo pyvista[all,trame] matplotlib jupyter

Or install from the repository:

pip install -e ".[mesh]"

Tutorial Overview#

Tutorial

Topic

What You’ll Learn

1. Getting Started

Core concepts

Mesh structure, data attachment, GPU acceleration

2. Operations

Mesh manipulation

Transformations, subdivision, slicing, merging

3. Discrete Calculus

Mathematical operators

Gradients, divergence, curl, curvature

4. Neighbors & Spatial

Queries

Adjacency, BVH, sampling, interpolation

5. Quality & Repair

Mesh health

Validation, quality metrics, repair

6. ML Integration

Production workflows

Performance, batching, torch.compile

7. Domain Mesh

Simulation domains

DomainMesh, boundaries, transforms, validation

8. I/O, Interop & Serialization

Getting data in/out

PyVista import/export, polygon tessellation, save/load

Running the Tutorials#

Option 1: Jupyter Notebook#

cd examples/minimal/mesh
jupyter notebook

Then open any tutorial_*.ipynb file.

Option 2: JupyterLab#

cd examples/minimal/mesh
jupyter lab

Option 3: VS Code / Cursor#

Open the .ipynb files directly - they work with the built-in notebook support.

Tutorial Contents#

Tutorial 1: Getting Started#

File: tutorial_1_getting_started.ipynb

Learn the core concepts - a Mesh is just 5 fields: 2 for geometry, 3 for data.

  • The 5-field data structure (points, cells, point_data, cell_data, global_data)

  • Creating meshes from scratch

  • Loading from PyVista and built-in primitives

  • Attaching scalar, vector, and tensor data

  • Visualization with .draw()

  • GPU acceleration with .to("cuda")

  • Autograd integration

Tutorial 2: Operations and Transformations#

File: tutorial_2_operations.ipynb

Learn mesh manipulation operations.

  • Geometric transformations (translate, rotate, scale, transform)

  • Subdivision schemes (linear, Loop, Butterfly)

  • Slicing (slice_cells, slice_points)

  • Merging multiple meshes

  • Boundary and facet extraction

  • Data conversion (cell_data_to_point_data, point_data_to_cell_data)

  • Topology checks (is_watertight, is_manifold)

Tutorial 3: Discrete Calculus and Differential Geometry#

File: tutorial_3_calculus.ipynb

Learn mathematical operations on meshes.

  • Computing gradients (LSQ and DEC methods)

  • Divergence and curl

  • Gaussian and mean curvature

  • Intrinsic vs extrinsic derivatives

  • Vector calculus identities

  • Physics-informed feature extraction

Tutorial 4: Neighbors, Adjacency, and Spatial Queries#

File: tutorial_4_neighbors_spatial.ipynb

Learn about mesh queries for GNN-style processing.

  • Topological neighbors (point-to-points, cell-to-cells)

  • Sparse adjacency encoding

  • BVH construction and queries

  • Point containment

  • Random point sampling

  • Data interpolation at query points

Tutorial 5: Quality, Validation, and Repair#

File: tutorial_5_quality_repair.ipynb

Learn mesh quality assessment and repair.

  • Quality metrics (aspect ratio, angles, quality score)

  • Mesh statistics

  • Validation (detect errors)

  • Repair operations (clean, remove duplicates, fix orientation)

  • Manifold and watertight checking

Tutorial 6: Integration with ML Workflows#

File: tutorial_6_ml_integration.ipynb

Learn to use PhysicsNeMo-Mesh in production ML pipelines.

  • Performance comparison with PyVista/VTK

  • Batching with padding for torch.compile

  • Feature extraction for ML models

  • Boundary condition handling

  • End-to-end CAE preprocessing workflow

  • torch.compile compatibility

Tutorial 7: Simulation Domains with DomainMesh#

File: tutorial_7_domain_mesh.ipynb

Learn to represent full simulation domains with interior meshes and named boundaries.

  • Building a DomainMesh from mesh primitives (cube volume + boundary surfaces)

  • Inspecting domain properties and iterating over meshes

  • Data augmentation via geometric transforms (quasi-equivariance)

  • Validation and boundary watertightness checking

  • Visualization of boundary patches by BC type

  • Domain-wide operations (subdivide, clean)

Tutorial 8: I/O - Interoperability and Serialization#

File: tutorial_8_io_interop.ipynb

Learn to get meshes in and out of PhysicsNeMo-Mesh.

  • The simplex-only data model (why importing usually means triangulating)

  • Importing from PyVista with from_pyvista (automatic triangulation)

  • Importing raw polygon soups with Adjacency + triangulate / Mesh.from_polygons

  • Convex vs non-convex polygons: ear clipping for correct areas and forces

  • Exporting to PyVista with to_pyvista

  • Saving and loading the native, folder-based memmap format, including its on-disk layout (.pmsh for Mesh, .pdmsh for DomainMesh)

Tutorial 9: Mesh Generation#

File: tutorial_9_mesh_generation.ipynb

Generate simulation-ready volume meshes from scratch in two ways.

From an explicit boundary (fill_interior):

  • Filling multiply-connected boundary meshes with per-boundary provenance data

  • Verifying the minimum-angle guarantee across resolutions

From an implicit function (mesh_implicit_domain, marching_cubes):

  • Using implicit CSG, raw level sets, and the coverage guard

  • Pinning sharp corners with feature_points

  • Tetrahedralizing 3D implicit domains

  • Extracting isosurfaces with marching_cubes

  • Computing shape gradients through the mesh (differentiable meshing)

Assets#

The assets/ directory contains pre-saved meshes for use in tutorials:

  • bunny.pt - Stanford bunny mesh (coarse, use .subdivide() for detail)

Additional Resources#