Search regions outside of many objects with a bounding box tree

[GuySten]

Description

This PR is stacked on the distance-caching PR (#4166), which is stacked on #4160. Only the last commit is new.

A cell that is the space outside of many objects, such as the water around rods or the matrix around TRISO particles, has a region that is the intersection of many children, one per object. Finding whether it contains a point, or where a ray leaves it, evaluates every child. This is why a flat model is much slower than the same model built with a lattice.

With this PR, when enough children of the root intersection are false only inside finite boxes, those children are put in a bounding volume hierarchy, built top-down with the binned surface area heuristic. Only two kinds of children are then evaluated:

• for a point, the children whose boxes contain it;
• for a ray, the children whose boxes the ray enters before the nearest boundary found so far.

The tree is used when at least 32 children have finite boxes and a point is in at most an eighth of the boxes on average, as estimated from their volumes. Other regions are evaluated as before. A region that is an intersection of half-spaces, such as the space outside of many spheres, is searched the same way.

Two more details:

• Working space: the surfaces of each child are stored consecutively, so a child is searched with working space for its own surfaces only. This keeps the tree effective in event-based mode, where the working space per particle is limited.
• Plane walls: children without finite boxes that are single half-spaces, such as the walls of a vessel made of many planes, are searched together in one pass over their surfaces, as for a simple region.

Results are unchanged apart from roundoff. The distance to a boundary reached after virtual crossings of other children is now added up over fewer steps. On the one model where this showed, the tally differs by 1.7e-16 relative and the particle histories are the same.

Results

Transport time, single thread, median of interleaved runs, compared with the distance-caching PR (#4166).

Model	Caching PR	This PR	Ratio
Randomly placed finite rods	404 s	0.44 s	0.0011
400 finite steel rods in a water tank	3.32 s	0.36 s	0.11
Flat TRISO (particles placed directly in the matrix)	214 s	87 s	0.41
10 cm slice of a flat TRISO compact	397 s	295 s	0.74
17 other models (ATR, FNG, PWR, shields, SCDR, lattice models, ...), 5 runs each			0.96–1.05

Adversarial models checked against develop:

• Ring of 360 sectors cut by planes through the axis: cell boxes overlap heavily, so the rule keeps the linear search. Within noise.
• 500-plane polygonal vessel holding 40 spheres: 0.87 s vs 0.90 s on develop. Before the plane walls were searched in one pass, this model was 2.4 times slower.

Testing

• test_box_tree.cpp: tree queries against brute force, including rays that miss every box.
• test_region.cpp: 20,000 random rays in a region outside of 40 finite rods. Each boundary found is checked to be where the ray leaves the region. The same boundaries are found with full working space, with working space for one child only, and with none.
• test_region_child_boxes.py: cells found and boundaries crossed in models with spheres and rods, compared with Python's evaluation of the regions.
• The full test suite passes locally. The only errors are tests that need ENDF data or dlopen, which fail the same way on develop.

Checklist

• I have performed a self-review of my own code
• I have run clang-format (version 18) on any C++ source files (if applicable)
• I have followed the style guidelines for Python source files (if applicable)
• I have made corresponding changes to the documentation (if applicable)
• I have added tests that prove my fix is effective or that my feature works (if applicable)