pyfracval.overlap_statistics
============================

.. py:module:: pyfracval.overlap_statistics

.. autoapi-nested-parse::

   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
---------------

.. py:function:: 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.