pyfracval.gap_scaling#

Convert a target inter-particle gap into a position-only scale factor.

Ported from YASF-new’s Config.cluster_gap_factor/cluster_gap_mode (yasfpy/config.py) – the target gap is expressed as a multiple of the mean particle radius (target_gap = gap_factor * r_mean), not an absolute length, so it’s meaningful across differently-scaled clusters.

This module only computes the scale – it never mutates or returns scaled coordinates. Applying the scale is a downstream concern (e.g. pyfastmm’s ParticlesConfig.gap_factor, which already does exactly positions *= gap_factor and needs nothing else changed): keeping that split means there is exactly one place a cluster’s geometry is actually transformed, however many places compute what to transform it by.

Module Contents#

pyfracval.gap_scaling.compute_gap_scale(coords, radii, gap_factor, mode='average')[source]#

Return the position-only scale factor that achieves gap_factor.

Parameters:

  • coords ((N, 3) array) – Particle center positions.

  • radii ((N,) array) – Particle radii, same units as coords.

  • gap_factor (float or None) – Target minimum surface-to-surface gap between neighboring particles, as a multiple of the mean particle radius. None or 0 means no gap requirement – returns 1.0 (the touching, as-generated case; a no-op for a caller that then does positions *= scale). Must be >= 0.

  • mode ({"average", "strict"}) –

    How gap_factor becomes a scale factor:

    • "average" (default, matching YASF’s own default): a cheap closed-form estimate from the mean radius, s = max(1, 1 + gap_factor / 2). Does not guarantee every pair individually clears the target gap for irregular (non-uniform-density) aggregates.

    • "strict": exact, via a KD-tree nearest-neighbor query – finds the scale that gives the closest pair exactly the target gap, which (since scaling every position by one global factor scales every pairwise distance by that same factor) guarantees every other pair, starting further apart, clears it too.

Returns:

The scale factor s such that coords * s achieves the requested gap. Always >= 1.0.

Return type:

float

Raises:

ValueError – If gap_factor is negative, mode is not one of the values above, or the resulting scale fails to eliminate all overlaps (checked directly, not assumed from the formula/computation).