Skip to content

Promote GLOBE rank schema utilities to physicsnemo.mesh#1769

Queued
peterdsharpe wants to merge 3 commits into
NVIDIA:mainfrom
peterdsharpe:psharpe/mesh-field-schemas
Queued

Promote GLOBE rank schema utilities to physicsnemo.mesh#1769
peterdsharpe wants to merge 3 commits into
NVIDIA:mainfrom
peterdsharpe:psharpe/mesh-field-schemas

Conversation

@peterdsharpe

@peterdsharpe peterdsharpe commented Jul 1, 2026

Copy link
Copy Markdown
Collaborator

Summary

This moves the rank-schema helpers already used by GLOBE into physicsnemo.mesh, where other mesh-based models can reuse them. GLOBE now imports the helpers from their shared location, and the old experimental module and re-exports are removed.

This is a code-ownership move rather than a new field-layout or packing API; the existing rank-schema behavior is preserved.

Testing

test/mesh/test_fields.py covers nested schemas, rank counting, TensorDict inference, and validation errors. Existing GLOBE tests continue to cover the consumers.

physicsnemo/mesh/fields.py introduces representation-neutral RankSpecDict helpers for flattening, validation, rank counting, TensorDict inference, and declared-data checks. It also adds ScalarVectorFields and a deterministic FieldLayout that packs and unpacks named rank-0 scalars and rank-1 polar vectors without mixing their transformation laws.

physicsnemo/mesh/__init__.py exports the schema and layout API from the stable mesh namespace so mesh-based models can share one field contract.

physicsnemo/experimental/models/globe/field_kernel.py and model.py now import these neutral utilities from physicsnemo.mesh. The old GLOBE-specific rank_spec.py module and its utilities/__init__.py re-exports are removed, while tensordict_utils.py points schema users to the mesh module.

test/mesh/test_fields.py verifies nested schemas, deterministic channel ordering, scalar/vector shape validation, round trips, empty layouts, and useful errors for missing or incorrectly ranked data.

Centralizing these semantics avoids model-specific duplication and gives future mesh layers a common, explicitly representation-aware field interface.
@copy-pr-bot

copy-pr-bot Bot commented Jul 1, 2026

Copy link
Copy Markdown

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

@peterdsharpe peterdsharpe requested a review from coreyjadams July 1, 2026 02:16
@greptile-apps

greptile-apps Bot commented Jul 1, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

This PR promotes GLOBE-specific rank-spec utilities into the shared physicsnemo.mesh namespace, deleting utilities/rank_spec.py and replacing its imports across field_kernel.py and model.py with a single from physicsnemo.mesh import … line. It also adds two new public types — ScalarVectorFields (a NamedTuple) and FieldLayout (a deterministic packer/unpacker that keeps scalar and polar-vector channels separate) — together with a new validate_rank_spec helper and a comprehensive test suite.

  • physicsnemo/mesh/fields.py is the core addition: it carries all migrated helpers plus FieldLayout, which sorts fields lexicographically and enforces dtype/device homogeneity on pack() and full shape validation on unpack().
  • physicsnemo/mesh/__init__.py exposes all new symbols in __all__, and the GLOBE utilities package drops its rank-spec re-exports (an intentional, experimental-API-level break).

Important Files Changed

Filename Overview
physicsnemo/mesh/fields.py New module introducing RankSpecDict helpers, ScalarVectorFields, and FieldLayout; one dead-code check in unpack() (vectors.shape[0] != n_points) is unreachable after the preceding shape equality assertion.
physicsnemo/mesh/init.py Adds re-exports for all public symbols from the new fields module alongside a complete all list; straightforward and correct.
physicsnemo/experimental/models/globe/utilities/rank_spec.py Deleted; functionality migrated to physicsnemo/mesh/fields.py with minor improvements (validate_rank_spec added to validate_data_contains_ranks path).
physicsnemo/experimental/models/globe/utilities/init.py Removes rank_spec re-exports; ranks_from_tensordict is no longer exported from this package (breaking change for callers using the old experimental path, which is intentional per the PR description).
physicsnemo/experimental/models/globe/field_kernel.py Import updated from the deleted rank_spec module to physicsnemo.mesh; local import ordering also tidied. No logic changes.
physicsnemo/experimental/models/globe/model.py Consolidates Mesh, RankSpecDict, flatten_rank_spec, and validate_data_contains_ranks into a single physicsnemo.mesh import block; no logic changes.
physicsnemo/experimental/models/globe/utilities/tensordict_utils.py Docstring cross-reference updated to point at the new physicsnemo.mesh.fields module; no code changes.
test/mesh/test_fields.py New test file covering flatten, validate, pack/unpack round-trips, equivariance, and error paths; one missing blank line between top-level test functions.

Reviews (1): Last reviewed commit: "Promote field schemas and layouts to phy..." | Re-trigger Greptile

Comment thread physicsnemo/mesh/fields.py Outdated
Comment thread test/mesh/test_fields.py Outdated
Remove a redundant point-count branch from FieldLayout.unpack(): the preceding full vector-shape check already enforces the same leading dimension. Restore the required separation between top-level field-schema tests.
@peterdsharpe

Copy link
Copy Markdown
Collaborator Author

/ok to test e3a91e2

Remove FieldLayout, ScalarVectorFields, validate_rank_spec, and their supporting tests and exports because they have no consumers on main. Keep this branch as a pure relocation of the RankSpecDict helpers already used by GLOBE; representation-aware packing can be introduced with the feature that needs it.
@peterdsharpe peterdsharpe changed the title Promote field schemas and layouts to physicsnemo.mesh Promote GLOBE rank schema utilities to physicsnemo.mesh Jul 1, 2026
@peterdsharpe

Copy link
Copy Markdown
Collaborator Author

/ok to test 2e66c44

@coreyjadams coreyjadams left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Straightforward relocation, seems reasonable to me!

@peterdsharpe peterdsharpe added this pull request to the merge queue Jul 1, 2026
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.

2 participants