Implement first set of fast approximation GWN methods by jcs15c · Pull Request #1791 · llnl/axom

jcs15c · 2026-02-02T21:54:38Z

Summary

This PR enhances the GWN capabilities of quest_winding_number_2d_ex (previously quest_winding_number_ex) and quest_winding_number_3d_ex by adding options for fast approximations of the GWN field. These methods are currently implemented for collections of 3D triangles and 2D lines as described in this paper.
To support this, the quest_winding_number_3d_ex example now has command line arguments to triangulate the input STEP file and evaluate its GWN field, and quest_winding_number_2d_ex now has command line arguments to linearize input curves. Subsequent containment decisions will faithfully reproduce the boundary of the discrete shape, but this will not exactly match the boundary of the curved surface. This leads to classification errors for points close to the surface.
New tests for 2D and 3D fast-approximate GWN methods have been added.

Algorithm Details

Briefly, these fast approximations work by adding each piece of the shape to a BVH spatial index, which is traversed at the given query point. During traversal:
- If the query point is far from the bounding box of an internal node, the contribution of all its children to the GWN is be approximated rapidly using a Taylor expansion.
- If the query point is near to or within the bounding box of an internal node, recurse to its children.
- If the query point is near to or within the bounding box of a leaf node, it's contribution to the GWN is computed exactly using a direct formula.

Implementation Details

Utilizing the existing BVH tree for this purpose required modifying it in the following ways:
- Adding a LinearBVHTraverser::reduce_tree(<LeafAction>) method which evaluates the LeafAction lambda on each leaf node to produce a value, then adding those values up the tree so that each internal node is associated with the sum of values for all its children. This returns an array of these values for each internal node.
- Adding an optional third positional argument to the search predicate lambda (i.e. the function which determines if a traverser should recurse at a given internal node) which contains an index to the internal node as laid out within the BVH.

~~This PR should consider the following before being un-drafted:~~ Done!

Extend quest_winding_number_3d_ex to take in .stl files directly as input.
Add more command line options to the 2D and 3D examples to permit changing Taylor approximation order
Add more command line options to the 3D example to permit direct evaluation of a triangulated STEP file instead of fast approximation, even if this would be significantly slower without a difference in quality.
Add a few extra tests to make sure containment decisions between the current direct methods and fast approximation methods agree.
Add a method to the quest STEP reader to get a bounding box directly from the .STEP file using OpenCascade.

jcs15c · 2026-02-13T19:07:47Z

 public:
  using NURBSCurve = axom::primal::NURBSCurve<double, 2>;
-  using CurveArrayView = axom::ArrayView<NURBSCurve>;
+  using CurveArrayView = axom::ArrayView<const NURBSCurve>;


I had to make this change for this to work more straight-forwardly with LinearizeCurves, since otherwise (to my knowledge) you can't use it to linearize a view of const objects without making a copy of all of them. But I think this is more close to how the class is actually implemented everywhere else, right? It doesn't seem to me like there's anywhere that a LinearizeCurves object ever needs to change a NURBSCurve in it's view.

kennyweiss

Partial review: first batch of comments

kennyweiss · 2026-03-04T20:04:36Z

+    }
+    else
+    {
+      // Do it in 2 stages.


Can you please expand on the two steps and why we need them for the non-seq policy?
Looks like step one is to compute on the leaf nodes and step 2 is to move it up the tree.
(whereas the seq policy branch does both)

I think the main benefit is just to improve the efficiency of operating over all the leaves, and I'm not certain that needs to be an exclusively parallel thing. I could probably rewrite reduce_recursion to not even take a lambda function, and just pass a view to the leaf array. I think @BradWhitlock originally wrote this, do you know of any particular reason it can't be done in two stages for both policies?

kennyweiss · 2026-03-04T20:15:34Z

@jcs15c -- is there a simple example or unit test we can add to spin for the new reduce_tree traverser? E.g. adding a random collection of points to a BVH by their bounding boxes and the counting the number of points contained within each inner node?

Yes, I'm sure I can come up with something. One way that's agnostic to the way the tree is constructed is that, if you have 8 points added to the BVH, then 8 inner nodes should contain one point (the leaves), 4 contain two points, 2 contain four points, and 1 contains all eight points, right?

kennyweiss

Thanks @jcs15c -- this looks great! I have a bunch of minor comments; nothing substantial.

kennyweiss · 2026-03-04T20:52:25Z

+std::string pjoin(const char *str, Args... args)
+{
+  return axom::utilities::filesystem::joinPath(std::string(str), pjoin(args...));
+}


@BradWhitlock -- should we move these pjoin functions to core/utilities? Perhaps in a separate PR?

kennyweiss · 2026-03-04T22:02:36Z

+ * the collection of geometric objects. 
+ */
+template <typename T, int NDIMS, int ORD>
+class GWNMomentData


Would it make sense to add some unit tests for the moment data computations? Or is this covered by the segment/triangle tests?

Added some for 2D segments and 3D triangles!

publixsubfan · 2026-03-05T01:01:06Z

+  template <typename ExecSpace, typename ValueType, typename LeafAction>
+  axom::Array<ValueType> reduce_tree(LeafAction&& lf,
+                                     int allocatorID = axom::getDefaultAllocatorID()) const
+  {


Is the eventual plan for this function to be invokable from inside a GPU kernel as a device function? If not, I'd suggest moving it into the standard BVH interface.

We'd like to, but are not there yet

As I understand it, a method like this couldn't go directly into the standard BVH interface because only LinearBVH describes how the data at internal nodes is actually arranged into arrays and arrayviews. This output of this function needs to align with that internal layout, and so if there was ever another implementation type for BVH, the actual logic of the function would have to change to reflect the internal layout of that other implementation. Does that seem consistent with how BVH.hpp and LinearBVH.hpp relate to one another?

kennyweiss · 2026-03-16T18:10:52Z

+        poly_mesh,
+        AXOM_LAMBDA(axom::IndexType cellIdx,
+                    const axom::numerics::Matrix<double>& coords,
+                    [[maybe_unused]] const axom::IndexType* nodeIds) {


hip is not happy w/ this attribute. Looks like we should change it to something like

Suggested change

[[maybe_unused]] const axom::IndexType* nodeIds) {

const axom::IndexType* /*nodeIds*/) {

... and similarly for the one below

No complaints here!

Arlie-Capps

@jcs15c , thank you for your hard work!

jcs15c · 2026-03-23T19:38:23Z

                string(CONCAT _pass_regex
                    "INOUT_STATS:.*"
-                    "pos_dofs=16.*"
+                    "pos_dofs=14.*"


Just for future reference, the new OCC-derived AABB method has slightly different bounds, so there are different numbers of contained points.

jcs15c self-assigned this Feb 2, 2026

jcs15c added enhancement New feature or request Quest Issues related to Axom's 'quest' component labels Feb 2, 2026

jcs15c marked this pull request as ready for review February 11, 2026 07:36

jcs15c requested review from Arlie-Capps, BradWhitlock, bmhan12, gunney1, kennyweiss and rhornung67 February 11, 2026 07:36

jcs15c changed the title ~~Implement first fast approximation GWN methods~~ Implement first set of fast approximation GWN methods Feb 11, 2026

jcs15c commented Feb 13, 2026

View reviewed changes

kennyweiss force-pushed the feature/kweiss/optimize-wn-3d branch from 9142cea to 4609f08 Compare February 14, 2026 01:32

kennyweiss force-pushed the feature/kweiss/optimize-wn-3d branch from 4609f08 to cfd9c5c Compare February 25, 2026 20:36

Base automatically changed from feature/kweiss/optimize-wn-3d to develop March 3, 2026 16:46

kennyweiss requested a review from publixsubfan March 4, 2026 19:18

kennyweiss added this to the FY26 Summer release milestone Mar 4, 2026

kennyweiss added Primal Issues related to Axom's 'primal component Spin Issues related to Axom's 'spin' component labels Mar 4, 2026

kennyweiss reviewed Mar 4, 2026

View reviewed changes

kennyweiss approved these changes Mar 4, 2026

View reviewed changes

publixsubfan reviewed Mar 5, 2026

View reviewed changes

jcs15c force-pushed the feature/spainhour/fast_gwn_triangles branch from 9993c59 to 0f31be3 Compare March 13, 2026 19:07

jcs15c added 7 commits March 16, 2026 10:03

Add opencascade bounding box method

4ffef3b

Refactor to look make flexible for future methods

b28e44b

Initial commit

04a1c0b

Update BVH implementation

8249204

Add 2D curve implementation

ef4f022

Refactor 2D example to look like 3D example

80ad46e

Add direct evaluation method for triangulated WN

ea7b999

jcs15c and others added 21 commits March 16, 2026 10:03

Add new test

d75b708

Add extra GWN methods

e8a46c1

Fix includes, rename test

e386dfe

Change flags for mfem-related quest tests

c2be2c6

Remove useless comment

b1ffad4

Use the right include for mesh utils

0360f5b

Guard step reader include

6745f16

flip foolish boolean

4b3376b

Fix the same thing a second time

673565b

Move methods to make shapes, add test

c05644d

Add doxygen comment for analytic surfaces file

85dc321

Improve documentation

ca60635

Improve CLI11 interface

044a5f2

Improve some comments throughout

db9a14d

Improve comments and readibility throughout

4c91abb

New tests and bugfix in methods

cd32693

Make method order 2 and 3D triangles

0ae4807

Streamline tests

2858e5d

fix a warning

3bd0475

Address a few warnings, fix test

f404808

Make device compatible

3f33b76

jcs15c force-pushed the feature/spainhour/fast_gwn_triangles branch from bc6e432 to 3f33b76 Compare March 16, 2026 17:15

kennyweiss reviewed Mar 16, 2026

View reviewed changes

jcs15c and others added 2 commits March 16, 2026 11:14

Remove maybe unused attribute

06def8f

Update RELEASE-NOTES.md

5e15dc7

Arlie-Capps approved these changes Mar 20, 2026

View reviewed changes

Merge branch 'develop' into feature/spainhour/fast_gwn_triangles

f1ccba6

jcs15c commented Mar 23, 2026

View reviewed changes

jcs15c merged commit db9bead into develop Mar 23, 2026
15 checks passed

jcs15c deleted the feature/spainhour/fast_gwn_triangles branch March 23, 2026 19:44

	[[maybe_unused]] const axom::IndexType* nodeIds) {
	const axom::IndexType* /nodeIds/) {

Conversation

jcs15c commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Algorithm Details

Implementation Details

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kennyweiss left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kennyweiss left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kennyweiss Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Arlie-Capps left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jcs15c commented Feb 2, 2026 •

edited

Loading

kennyweiss Mar 16, 2026 •

edited

Loading