Finish 2 pass candidate search

[gunney1]

Summary

• This PR is a refactoring
• It does the following:
  • Change the two computeClipVolumes3D methods to call the workhorse computeClipVolumes3DTet, which implements the two-pass candidate search (see PR Use 2-pass candidate search for mesh clipping #1756). This is facilitated by two temporary index lists that computeClipVolumes3DTet require.
  • Add a few comments and error checks that didn't make it into previous PRs in this series.

This PR, along with #1756, resolves issue #1704.

Performance data

Test problem

I collected clipping times using a 100^3 cubic computational mesh. Each test geometry takes between 6.1% and 9.7% of the domain. I added a "cupmesh", which is a tetrahedral mesh representation of a cup, from the data/quest/cup.proe file. This image is for illustration only. The actual shapes are bigger and centered on the mesh.

Timers

The benchmarks were run on 1 rank, using OpenMP on rzwhippet and HIP on rzadams. Here are the times spent clipping each geometry, the median of 5 repetitions. The "sl" column headings below indicate the level of screening used to avoid unneeded call to the clipping function.

• sl0: no screening
• sl1: screen out cells using geometry-specific algorithms
• sl2: decompose each remaining cell from sl1 into 6 non-degenerate tets and screen the tets.
• sl3: sl2 plus try to determine in/out relationship between 2 primitives before computing their overlap volumes.

On rzwhippet:

                                      sl0    sl1    sl2    sl3
    clipping:cone.0                 2.012  1.386  1.249  1.258
    clipping:cupmesh.0             18.410  2.335  0.927  0.806
    clipping:cyl.0                  2.177  0.518  0.453  0.452
    clipping:hex.0                 11.436  0.917  0.291  0.238
    clipping:sor.0                  5.088  1.112  0.982  0.969
    clipping:tet.0                  9.182  0.357  0.115  0.114
    clipping:tetmesh.0             16.058  1.148  0.413  0.357

On rzadams:

                                     sl0    sl1    sl2    sl3
    clipping:cone.0                0.658  0.278  0.258  0.259
    clipping:cupmesh.0             0.811  0.284  0.281  0.306
    clipping:cyl.0                 0.662  0.193  0.207  0.208
    clipping:hex.0                 0.669  0.176  0.201  0.231
    clipping:sor.0                 0.971  0.221  0.236  0.235
    clipping:tet.0                 0.646  0.170  0.164  0.163
    clipping:tetmesh.0             0.696  0.245  0.246  0.246

Remarks about the performance times

• The largest gain comes from sl1, the simplest screening. The higher screening levels build on this one.
• The other screening levels had small but non-trivial gains on rzwhippet. On rzadams, the gain was negligible and even lost a little in one case. I think it's likely that with a denser computational mesh, this will different. As always, keep in mind that performance is highly configuration-dependent.
• The gain from sl1 to sl2 was better before we switched from a 24-tet decomposition to a 18-tet decomposition, which was really a 6-tet decomposition on a cartensian mesh. This makes sense because the larger tets are more likely to intersect the geometry's boundary.
• The detailed timers show that the time spent screening is little to negligible.
• All screen levels benefit from the 2-pass candidate search. This is not a comparison of the 2-pass vs the single-pass. The original implementation in IntersectionShaper used single-pass and was significantly slower.