pyfracval.quality#

Final-aggregate quality measurement.

Answers two questions about a finished aggregate that nothing else in the pipeline asks:

  1. Is the geometry actually valid? success in the catalog means “PCA+CCA reached the requested particle count”, which says nothing about whether the saved coordinates are overlap-free. Clusters marked successful have been found carrying severe residual overlap (see docs/source/catalog_overlap_leak.md). Measuring the finished geometry once, at the end, closes that whole class of leak structurally rather than by chasing individual entry points.

  2. Did it land on the scaling law? The per-merge Gamma machinery aims at the prescribed Df/kf, but the pairing relaxation factor and the adaptive overlap tolerance both accept merges slightly off-target, and nothing measures the result.

Cheap enough to run unconditionally: one O(N^2) pass over a few hundred to a few thousand particles, once per aggregate, against a generation that took seconds to minutes.

Module Contents#

pyfracval.quality.max_self_overlap(coords, radii, min_overlap=1e-12)[source]#

Largest and total count of residual overlaps within one aggregate.

The overlap fraction uses the same normalization as the sticking tolerance tol_ov - ((r_i + r_j) - d_ij) / (r_i + r_j) - so the result is directly comparable against it. (Note densify._self_overlap_pairs_kernel normalizes by min(r_i, r_j) instead, for its own push-apart geometry; the two numbers are not interchangeable.)

Parameters:

min_overlap (float) – Ignore overlaps at or below this. Particles are placed in point contact, so a correctly-built aggregate has many pairs sitting at |overlap| ~ 1e-15 purely from floating-point round-off in the rigid transforms. Counting those would report every healthy aggregate as having dozens of “overlapping pairs”.

Returns:

(max_overlap_fraction, n_overlapping_pairs). The fraction is 0.0 when nothing overlaps beyond min_overlap.

Return type:

tuple[float, int]

pyfracval.quality.compute_aggregate_quality(coords, radii, df, kf, tol_ov, n_particles_dropped=0, densities=None)[source]#

Measure a finished aggregate against what was asked for.

Parameters:

  • coords (np.ndarray) – The final aggregate geometry.

  • radii (np.ndarray) – The final aggregate geometry.

  • df (float) – The prescribed fractal parameters, for the scaling-law target.

  • kf (float) – The prescribed fractal parameters, for the scaling-law target.

  • tol_ov (float) – The overlap tolerance the run was generated under; used to decide overlap_ok.

  • n_particles_dropped (int) – Particles removed by drop-rescue, passed through for the record.

Returns:

max_residual_overlap, n_overlapping_pairs, overlap_ok, measured_rg (paper Eq. 4), scaling_law_rg, rg_error_pct, n_particles, n_particles_dropped.

Return type:

dict