pyfracval.overlap#

Overlap calculation dispatch for PyFracVAL.

Functions for computing maximum overlap between particle clusters, with variants for PCA, CCA, fast, parallel, and auto-dispatch modes.

The overlap tolerance and sticking feasibility checks are used in the PCA/CCA workflow of [Morán et al., 2019].

Constants#

PARALLEL_OVERLAP_THRESHOLD

Minimum cluster size to trigger parallel overlap calculation.

Functions#

calculate_max_overlap_cca

Full pairwise overlap calculation for CCA cluster pair.

calculate_max_overlap_pca

Full pairwise overlap calculation for PCA cluster pair.

calculate_max_overlap_pca_fast

Optimised overlapping-spheres overlap for PCA.

calculate_max_overlap_cca_fast

Optimised overlapping-spheres overlap for CCA.

calculate_max_overlap_pca_parallel

Parallel overlap calculation for PCA cluster pair.

calculate_max_overlap_cca_parallel

Parallel overlap calculation for CCA cluster pair.

calculate_max_overlap_pca_auto

Auto-dispatch overlap for PCA (chooses fast vs parallel).

calculate_max_overlap_cca_auto

Auto-dispatch overlap for CCA (chooses fast vs parallel).

Module Contents#

pyfracval.overlap.calculate_max_overlap_cca(coords1, radii1, coords2, radii2)[source]#

Calculate max overlap between two particle clusters (Numba optimized).

Overlap is defined as 1 - distance / (radius1 + radius2) for overlapping pairs, max(0).

Parameters:

  • coords1 (np.ndarray) – Nx3 coordinates of cluster 1.

  • radii1 (np.ndarray) – N radii of cluster 1.

  • coords2 (np.ndarray) – Mx3 coordinates of cluster 2.

  • radii2 (np.ndarray) – M radii of cluster 2.

Returns:

Maximum overlap fraction found between any particle in cluster 1 and any particle in cluster 2. Returns 0.0 if no overlap.

Return type:

float

pyfracval.overlap.calculate_max_overlap_pca(coords_agg, radii_agg, coord_new, radius_new)[source]#

Calculate max overlap between a new particle and an aggregate (Numba).

Overlap is defined as 1 - distance / (radius_new + radius_agg) for overlapping pairs, max(0).

Parameters:

  • coords_agg (np.ndarray) – Nx3 coordinates of the existing aggregate.

  • radii_agg (np.ndarray) – N radii of the aggregate particles.

  • coord_new (np.ndarray) – 3D coordinates of the new particle.

  • radius_new (float) – Radius of the new particle.

Returns:

Maximum overlap fraction found between the new particle and any particle in the aggregate. Returns 0.0 if no overlap.

Return type:

float

pyfracval.overlap.calculate_max_overlap_pca_fast(coords_agg, radii_agg, coord_new, radius_new, tolerance=1e-06)[source]#

Calculate max overlap with early termination (optimized for speed).

This optimized version includes: 1. Early termination: Returns immediately when overlap exceeds tolerance 2. Bounding sphere pre-check: Avoids sqrt for particles far apart 3. Sequential execution: Trades parallelization for early exit

Overlap is defined as 1 - distance / (radius_new + radius_agg).

Performance: ~2-3x faster than parallel version when overlap is found early.

Parameters:

  • coords_agg (np.ndarray) – Nx3 coordinates of the existing aggregate.

  • radii_agg (np.ndarray) – N radii of the aggregate particles.

  • coord_new (np.ndarray) – 3D coordinates of the new particle.

  • radius_new (float) – Radius of the new particle.

  • tolerance (float, optional) – Overlap tolerance threshold for early termination (default: 1e-6).

Returns:

Maximum overlap fraction found. Returns immediately if overlap > tolerance.

Return type:

float

pyfracval.overlap.calculate_max_overlap_cca_fast(coords1, radii1, coords2, radii2, tolerance=1e-06)[source]#

Calculate max overlap between clusters with early termination (optimized).

This optimized version includes: 1. Early termination: Returns immediately when overlap exceeds tolerance 2. Bounding sphere pre-check: Avoids sqrt for particles far apart 3. Sequential execution: Trades parallelization for early exit

Overlap is defined as 1 - distance / (radius1 + radius2).

Performance: ~2-3x faster than parallel version when overlap is found early.

Parameters:

  • coords1 (np.ndarray) – Nx3 coordinates of cluster 1.

  • radii1 (np.ndarray) – N radii of cluster 1.

  • coords2 (np.ndarray) – Mx3 coordinates of cluster 2.

  • radii2 (np.ndarray) – M radii of cluster 2.

  • tolerance (float, optional) – Overlap tolerance threshold for early termination (default: 1e-6).

Returns:

Maximum overlap fraction found. Returns immediately if overlap > tolerance.

Return type:

float

pyfracval.overlap.calculate_max_overlap_pca_parallel(coords_agg, radii_agg, coord_new, radius_new)[source]#

Calculate max overlap for PCA with parallel execution (no early termination).

This version uses Numba prange to parallelize overlap checks across all aggregate particles. Trade-off: No early termination, but faster for large N.

Use for n_agg > PARALLEL_OVERLAP_THRESHOLD (~200 particles).

Parameters:

  • coords_agg (np.ndarray) – Current aggregate coordinates (n_agg, 3)

  • radii_agg (np.ndarray) – Current aggregate radii (n_agg,)

  • coord_new (np.ndarray) – New particle coordinates (3,)

  • radius_new (float) – New particle radius

Returns:

Maximum overlap fraction found across all particles

Return type:

float

pyfracval.overlap.calculate_max_overlap_cca_parallel(coords1, radii1, coords2, radii2)[source]#

Calculate max overlap for CCA with parallel execution (no early termination).

This version uses Numba prange to parallelize overlap checks. Computes all pair overlaps in parallel.

Use for n1 * n2 > PARALLEL_OVERLAP_THRESHOLD (~200 pairs).

Parameters:

  • coords1 (np.ndarray) – Cluster 1 coordinates (n1, 3)

  • radii1 (np.ndarray) – Cluster 1 radii (n1,)

  • coords2 (np.ndarray) – Cluster 2 coordinates (n2, 3)

  • radii2 (np.ndarray) – Cluster 2 radii (n2,)

Returns:

Maximum overlap fraction found across all particle pairs

Return type:

float

pyfracval.overlap.calculate_max_overlap_pca_auto(coords_agg, radii_agg, coord_new, radius_new, tolerance=1e-06)[source]#

Auto-dispatch to parallel or sequential overlap check based on size.

For large aggregates (n > PARALLEL_OVERLAP_THRESHOLD), uses parallel version without early termination. For small aggregates, uses sequential with early exit.

Parameters:

  • coords_agg (np.ndarray) – Current aggregate coordinates (n_agg, 3)

  • radii_agg (np.ndarray) – Current aggregate radii (n_agg,)

  • coord_new (np.ndarray) – New particle coordinates (3,)

  • radius_new (float) – New particle radius

  • tolerance (float, optional) – Overlap tolerance for early termination (default: 1e-6)

Returns:

Maximum overlap fraction

Return type:

float

pyfracval.overlap.calculate_max_overlap_cca_auto(coords1, radii1, coords2, radii2, tolerance=1e-06)[source]#

Check max overlap between two clusters during CCA sticking.

FIX (PyFracVAL-xwx): Always use the sequential early-termination path. The previous parallel dispatch was counterproductive for CCA: in sticking, clusters are placed touching (high overlap probability), so early termination fires almost immediately. The parallel path computes ALL n1*n2 pairs even when the first pair already overlaps, making it 78x slower for large clusters.

Benchmark (n1=n2=256, 65536 pairs): parallel=109µs, fast=1.4µs.

Parameters:

  • coords1 (np.ndarray) – Cluster 1 coordinates (n1, 3)

  • radii1 (np.ndarray) – Cluster 1 radii (n1,)

  • coords2 (np.ndarray) – Cluster 2 coordinates (n2, 3)

  • radii2 (np.ndarray) – Cluster 2 radii (n2,)

  • tolerance (float, optional) – Overlap tolerance for early termination (default: 1e-6)

Returns:

Maximum overlap fraction

Return type:

float