pyfracval.overlap_statistics

Opt-in, off-hot-path overlap-failure census for CCA sticking attempts.

pyfracval/overlap.py’s CCA overlap-check functions return a single scalar (max overlap fraction) and early-exit the instant any pair exceeds tolerance - load-bearing for performance (see docs/source/gpu_acceleration.md: numba beats JAX by 1-4 orders of magnitude specifically because of this early-exit/branch-skipping behavior). This module is deliberately not a modification of that hot path. Instead, on a failed sticking attempt, it runs one full (non-early-exit) pairwise scan between the two clusters to answer a question the scalar check can’t: how many particles overlap, and by how much - severity data the binary success/fail signal throws away.

Modeled directly on pyfracval/densify.py’s _self_overlap_pairs_kernel (same full-scan, no-early-exit, capped-output design), adapted from a single-set self-overlap scan to a two-cluster cross-overlap scan.

Module Contents

pyfracval.overlap_statistics.compute_overlap_census(coords1, radii1, coords2, radii2, max_pairs=4096)

Run the full cross-overlap scan and package the result as an OverlapCensus. Cost is O(n1*n2) with no early exit - intended to run once, on a failed attempt, never on the hot path.