Adds parametric type system for PhysicsNeMo-Mesh

[peterdsharpe]

Parametric type hints for Mesh

Adds subscript syntax to Mesh so that Mesh[2, 3] denotes a 2-dimensional manifold embedded in 3-dimensional space. This enables dimension-aware type annotations and runtime isinstance checks with no changes to Mesh's data model or serialization.

Subscript syntax

Mesh[m, s] always takes exactly two parameters. Use ... (Ellipsis) for an unconstrained dimension. Concrete integer dimensions are validated at spec-creation time (non-negative, manifold <= spatial). Symbolic string labels like "n-1" are parsed and, when both dimensions share a variable, the implied codimension is validated at isinstance time.

Mesh[2, 3]          # 2d manifold in 3d space
Mesh[1, ...]        # 1d manifold in any space
Mesh[..., 3]        # any manifold in 3d space
Mesh["n-1", "n"]    # codimension-1 manifold

isinstance(mesh, Mesh[2, 3])   # True for a triangle mesh in 3D
Mesh[2, 3].boundary            # -> Mesh[1, 3]
Mesh[2, 3] is Mesh[2, 3]       # True (cached)

Checklist

• I am familiar with the Contributing Guidelines.
• New or existing tests cover these changes.
• The documentation is up to date with these changes.
• The CHANGELOG.md is up to date with these changes.
• An issue is linked to this pull request.
• If I am implementing a new model or modifying any existing model, I have followed the Models Implementation Coding Standards.

Dependencies

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.

[greptile-apps]

Greptile Summary

This PR adds a parametric type system for PhysicsNeMo-Mesh, enabling Mesh[m, s] subscript syntax for dimension-aware type annotations and runtime isinstance checks. The implementation is well-structured: a new _mesh_spec.py module contains the frozen MeshDims dataclass, a _MeshSpecMeta metaclass that hooks __instancecheck__, and a module-level identity-preserving cache (Mesh[2, 3] is Mesh[2, 3]). The Mesh class gains __class_getitem__, two convenience aliases (PointCloud, Graph) are added to __init__.py, and the repr format is updated from Mesh(manifold_dim=m, spatial_dim=s, ...) to Mesh[m, s](...).

Key items to be aware of:

• Note on repr breaking change: The updated repr format (Mesh[2, 3](...) vs. the previous Mesh(manifold_dim=2, spatial_dim=3, ...)) is a user-visible breaking change for any downstream code that parses or pattern-matches against the repr string. The test suite is updated accordingly, but this should be called out in the changelog/release notes.
• Logic concern in matches(): When a symbolic string dimension is paired with an unconstrained (None) dimension — e.g. Mesh["n-1", ...] — the symbolic constraint is silently never evaluated and the spec matches all meshes. The PR's design intentionally restricts symbolic codimension checks to cases where both dimensions share a variable, but this "no-op" case is not tested and may confuse users.
• Minor performance: _parse_dim_expr re-runs the regex on every isinstance call inside _check_symbolic_constraint, despite the expressions being immutable after MeshDims construction. Pre-computing the (variable, offset) pairs in __post_init__ would avoid redundant work.

Important Files Changed

Filename	Overview
physicsnemo/mesh/_mesh_spec.py	New core module implementing the parametric type system. Contains MeshDims dataclass, _MeshSpecMeta metaclass, and the cached factory. Two logic concerns: (1) symbolic constraints are silently dropped when only one dimension is a string, making Mesh["n-1", ...] match all meshes with no warning; (2) _parse_dim_expr is called on every isinstance check despite immutable inputs.
physicsnemo/mesh/mesh.py	Adds class_getitem classmethod to enable Mesh[m, s] syntax. Implementation correctly validates param count and type before delegating to _get_mesh_spec. No issues found.
test/mesh/test_mesh_spec.py	Comprehensive test suite for the new parametric type system, covering isinstance checks, caching, symbolic constraints, boundary derived types, and MeshDims dataclass. Missing a test for the Mesh["n-1", ...] (symbolic + unconstrained) edge case which always matches all meshes.

_{Last reviewed commit: 32c1b63}

[coreyjadams]

I don't have any particular objection to this though I kind of liked the old way better. It was more explicit: you are used to writing this every day and remember if the manifold dimension or spatial dimension is first but the rest of us don't. I liked using the keywords.

Is this just for representations? Or is this driving type checking and match cases too?

[peterdsharpe]

/blossom-ci

[peterdsharpe]

Thanks for the speedy review @coreyjadams ! :)

Re:

I kind of liked the old way better. It was more explicit: you are used to writing this every day and remember if the manifold dimension or spatial dimension is first but the rest of us don't. I liked using the keywords.

So, the nice thing here is that it's actually unambiguous, since n_manifold_dims <= n_spatial_dims, always. So, even if you don't remember the order:

• Mesh[2, 3] must be a 2d manifold embedded in 3d space. (Since a 3d manifold cannot be embedded in 2d space.)
• Mesh[3, 3] is also unambiguous, since both the manifold dim and the spatial dim are the same.

This ordering also matches how mathematicians discuss these: "Let M be a 2d manifold in 3d space" -> "Mesh[2, 3]".

My feeling is that the conciseness (at least in terms of type signatures) is a nice win here, especially as we start doing more complicated Mesh ops (e.g., bundling a surface mesh and a volume mesh together, so we can manipulate them as one).

That said, I can see how having it be more explicit in the repr might be more readable for new users, and in printouts. I'll make it so that the repr defaults to the older style (Mesh[n_manifold_dims=2, n_spatial_dims=3]), while still allowing for Mesh[2, 3] in type signatures.

[peterdsharpe]

/blossom-ci

[NickGeneva]

/blossom-ci

[NickGeneva]

/blossom-ci