Initial clipping code re-factor #1667

gunney1 · 2025-09-24T11:22:49Z

Summary

This PR is an initial refactoring of the clipping code in IntersectionShaper.
IntersectionShaper has 4 significant jobs that make it big and a bit unwieldy.
1. Clip user-specified geometries against the cells of a mesh to compute overlap volumes. Clipping accounts for more than 95% of the time spent in shaping and is the motivation for the current effort. The intention is to provide fast clipping functionality for IntersectionShaper to use.
2. Combine overlap volumes using replacement rules.
3. Support multiple mesh formats (Blueprint and MFEM) stored in multiple hierarchy classes (Sidre and Conduit).
4. Support multiple execution spaces to be selected by the user at run time.
This PR
- Contains the bulk of the refactoring work, introducing key classes and interfaces.
- Implements the clipping code outside of IntersectionShaper. The idea is to eventually remove the IntersectionShaper's clipping code and use the new clipping code instead.
- Introduces well-defined interfaces to support shape-specific approaches to improve clipping performance. Clipping involves some shape-specific operations and some common operations. Both have been re-factored to support a variety of potentially faster algorithms.
- Begins implementing shape-specific clipping approaches. The tetrahedral shape is included here as an example. More will follow in Improve clipping code performance #1654.
- Provides a mesh wrapper that presents basic and derived mesh data as ArrayView objects, regardless of whether the mesh is Blueprint or MFEM, and stored in Sidre or Conduit. This part is a work-in-progress in that MFEM support has not started.

Completed work

The MeshClipper class provides the access point for the clipping functionality.
- MeshClipper::clip computes the overlap volume for every cell in the mesh.
- The MeshClipper::clip method uses fast geometry-specific operations where they are available and falls back on a general method where they aren't.
- The general method, discretizing the geometry and checking its discrete pieces against every zone, was taken from the IntersectionShaper. This general method is the only choice when using the current IntersectionShaper.
- The general method is provided by MeshClipperImpl, a class templated on execution-space . This class contains computeClipVolumed3D, the code taken from IntersectionShaper. The two other versions of this method do the same thing but on a subset of cells or tets (from cells) that excludes those outside or inside the geometry.
Geometry-specific operations are implemented through the abstract base class MeshClipperStrategy.
- This is where geometry-specific operations are implemented (if available), such as fast screening operations and specialized clipping code.
  - Screening is the process of determining whether a mesh cell is completely outside or completely inside a geometry. Cells that can be labeled this way are excluded from the much more expensive clipping operation.
  - An example of specialized clipping is for the plane geometry. which takes advantage of its simplicity.
The ShapeMesh encapsulates the mesh being shaped into. It provides a uniform interface for accessing the mesh data, regardless of whether the data is stored in Conduit or Sidre or by blueprint or (future) MFEM convention. ShapeMesh also computes and caches a variety of mesh-dependent data to amortize their cost among all clipping geometries.
Test for MeshClipper.

New codes are in namespace experimental, because this is a work in progress.

Dependencies

The mesh clipping refactor includes multiple PRs. Please review these before this one.

… into feature/gunney/initial-mesh-clipper

…-mesh-clipper

src/axom/quest/MeshClipperStrategy.hpp

src/axom/quest/ShapeMesh.cpp

src/axom/quest/MeshClipper.cpp

src/axom/quest/detail/clipping/MeshClipperImpl.hpp

src/axom/quest/MeshClipper.hpp

src/axom/quest/detail/clipping/MeshClipperImpl.hpp

Arlie-Capps

I found a few typos and unclear spots, a possible data write conflict within a loop, and a need for refactoring three methods down to one. Let's chat about the loop: perhaps I don't understand what is going on well enough.

The refactoring three methods to one needs to happen, but we can do it when this gets moved out of experimental namespace.

Arlie-Capps

@gunney1 , I appreciate your work on this, and your fixes. As we discussed, there is work to be done in a future PR. This one looks to be in a good shape.

…-mesh-clipper

kennyweiss

Thanks @gunney1 -- lots of good work in here.

I have some concerns related to the generality of ShapeMesh and the overlap in functionality between this and bump, but I think we'll work these out in the future when we pull this out of the experimental namespace.

In the immediate term, since you're guarding sidre in some cases, I want to make sure that this compiles properly when AXOM_ENABLE_SIDRE is off.

src/axom/quest/ShapeMesh.hpp

src/axom/quest/detail/clipping/TetClipper.hpp

kennyweiss · 2025-11-04T19:17:44Z

src/axom/quest/MeshClipperStrategy.cpp

+/*!
+ * \brief Implementation of a GeometryOperatorVisitor for processing klee shape operators
+ *
+ * This class extracts the matrix form of supported operators.
+ * For other operators, it sets the valid flag to false.
+ * To use, check the \a isValid() function after visiting and then call the \a getMatrix() function.
+ */
+class AffineMatrixVisitor : public klee::GeometryOperatorVisitor


Note (likely for a future PR) -- I think these should be available directly in Klee rather than in Quest,
e.g. here as well:

https://github.com/LLNL/axom/blob/adc75e2af3abce9ef134172410b0e55dc615009f/src/axom/quest/DiscreteShape.cpp#L21-L74

See also: #1628

kennyweiss · 2025-11-04T19:20:30Z

src/axom/quest/MeshClipperStrategy.cpp

+const axom::primal::BoundingBox<double, 2>& MeshClipperStrategy::getBoundingBox2D() const
+{
+  static const axom::primal::BoundingBox<double, 2> invalidBb2d;
+  return invalidBb2d;
+}


I think this should return by value to avoid the static instance (see comment in header)

src/axom/quest/tests/CMakeLists.txt

src/axom/quest/detail/clipping/MeshClipperImpl.hpp

This reverts commit 02f7c01. That commit tried to update the compiler to fix a probable compiler bug, but the 6.4 may have other bugs.

gunney1 · 2025-11-05T16:09:58Z

Thanks @gunney1 -- lots of good work in here.

I have some concerns related to the generality of ShapeMesh and the overlap in functionality between this and bump, but I think we'll work these out in the future when we pull this out of the experimental namespace.

In the immediate term, since you're guarding sidre in some cases, I want to make sure that this compiles properly when AXOM_ENABLE_SIDRE is off.

Good point @kennyweiss. I fixed the new code and made an issue for an existing non-sidre build, #1708

Initial mesh clipper refactoring.

66a889c

gunney1 added this to the 2025 Fall Release milestone Sep 24, 2025

gunney1 requested review from Arlie-Capps, BradWhitlock, bmhan12, kennyweiss, publixsubfan and rhornung67 September 24, 2025 11:22

gunney1 self-assigned this Sep 24, 2025

gunney1 added Quest Issues related to Axom's 'quest' component GPU Issues related to GPU development labels Sep 24, 2025

gunney1 mentioned this pull request Sep 24, 2025

Improve clipping code performance #1654

Draft

Merge remote-tracking branch 'gh/feature/gunney/extend-klee-geometry'…

2f0b0dc

… into feature/gunney/initial-mesh-clipper

Base automatically changed from feature/gunney/extend-klee-geometry to feature/gunney/extend-primal-geometries September 30, 2025 23:53

Base automatically changed from feature/gunney/extend-primal-geometries to develop October 1, 2025 20:27

gunney1 added 2 commits October 1, 2025 13:30

Merge remote-tracking branch 'gh/develop' into feature/gunney/initial…

9273714

…-mesh-clipper

Adjust to removed template parameters in methoc clip.

07fd4e9

gunney1 removed this from the 2025 Fall Release milestone Oct 1, 2025