Geometry Guardrail

[mnabian]

PhysicsNeMo Pull Request

Description

This PR introduces a new experimental module (physicsnemo.experimental.guardrails) for detecting out-of-distribution geometric configurations in CAD models and simulation meshes using density-based anomaly detection. The module extracts 22 non-invariant geometric features (centroid, PCA axes/eigenvalues, bounding box, surface areas) and supports two density estimation methods: Gaussian Mixture Models (GMM) with optional GPU acceleration, and Polynomial Chaos Expansion (PCE) using Hermite polynomials (currently CPU only). Key features include parallel STL loading with multiprocessing, optional Rust-based fast I/O adapter, three-level classification (OK/WARN/REJECT) based on empirical percentiles, production-ready serialization with automatic schema versioning, and comprehensive tests and documentation. The API is simple (GeometryGuardrail.fit(meshes) / .query(meshes)), and handles optional dependencies gracefully (Rust reader).

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 Overview

Greptile Summary

This PR adds an experimental physicsnemo.experimental.guardrails.geometry module implementing a GeometryGuardrail API that featurizes meshes/STLs and performs OOD detection via density models (Torch GMM and PCE). It also adds multiprocessing-based STL feature extraction utilities, serialization/load logic with schema/version checks, and a comprehensive test suite plus minimal example docs/scripts.

Key merge blockers are: (1) the changelog entry points at the wrong import path (guardrail vs guardrails), (2) GeometryDensityModel.percentiles() uses an O(N·M) broadcast compare that will not scale to realistic dataset sizes (and can OOM on GPU), (3) GeometryGuardrail.fit()/query() attempt to move Mesh to CUDA and then use mesh-derived tensors; if mesh internals aren’t consistently moved/constructed on that device this can error on GPU, conflicting with the stated “mesh operations always on CPU”, and (4) test_density_model.py uses NumPy ops on torch tensors returned by score().

Important Files Changed

Filename	Overview
CHANGELOG.md	Adds a geometry guardrail changelog entry; entry currently uses the wrong module path (guardrail vs guardrails).
physicsnemo/experimental/guardrails/geometry/density_model.py	Adds torch-based unified density model wrapper; percentile computation uses an O(N·M) broadcast compare that will not scale.
physicsnemo/experimental/guardrails/geometry/feature_extraction.py	Implements GPU-capable geometric feature extraction; relies on Mesh tensor attributes being resident on the requested device.
physicsnemo/experimental/guardrails/geometry/mesh_io.py	Adds multiprocessing STL loading + feature extraction; prints errors to stdout and enforces pyvista availability via decorators.
physicsnemo/experimental/guardrails/geometry/ood_detector.py	Implements GeometryGuardrail end-to-end fit/query/save/load; fit/query attempt to move Mesh to device but feature extraction may not be device-safe for Mesh internals.
test/experimental/guardrails/geometry/test_density_model.py	Updates/introduces density model tests; currently assumes score outputs are NumPy but implementation returns torch tensors.

[greptile-apps]

_{8 files reviewed, 8 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Additional Comments (1)

test/models/graphcast/utils/test_loss.py
Unconditional CUDA tensors

test_loss() always allocates tensors on device="cuda" (lines 29-31). This will hard-fail on CPU-only test runs even when sklearn is present, because the only skip guard is @requires_module("sklearn"). Gate this test on CUDA availability (or parameterize over the existing device fixture) so CI without GPUs can run the suite.

[mnabian]

@coreyjadams could you review this new physicsnemo.experimental.guardrails subpackage and let me know if it fits well within our overall refactor standards? Also, I need your input on the stlreader/ Rust directory—should we integrate it with pyproject.toml and the main PhysicsNemo build system, keep it as-is with the separate manual build, or just remove it from the PR for now due to packaging concerns? Or do you have any other suggestions for better packaging this? Thanks!

[mnabian]

Depends on #1362 for CI to pass.

[mnabian]

/blossom-ci

[mnabian]

/blossom-ci

[mnabian]

/blossom-ci

[greptile-apps]

_{6 files reviewed, 4 comments}

_{Edit Code Review Agent Settings | Greptile}

[mnabian]

/blossom-ci

[mnabian]

@ktangsali thanks for reviewing this PR and for your great comments! All of your comments are addressed, please re-review. The most concerning comment for me was the potential bug in handling STLs with multiple solids. I verified that pyvista merges multi-solid STLs into a single mesh when loading, so that is not an issue.

[mnabian]

/blossom-ci

[mnabian]

/blossom-ci

[mnabian]

/blossom-ci

[ktangsali]

Looks good! Thanks for addressing my comments. Approved with only a minor follow up on previous comment.

[coreyjadams]

Approving!