pyfracval.densify#

Post-aggregation densification for high-Df fractal aggregates.

Generates aggregates at a feasible Df (e.g. 2.0) then compresses them toward the target Df (e.g. 2.25) using radial compression followed by iterative overlap resolution. Optionally uses Voronoi-guided migration for better structural preservation.

Two methods are provided:

  • radial: uniform radial compression toward CM, then overlap push-apart

  • voronoi: Voronoi-guided migration of under-dense particles inward

Both methods are opt-in via OrchestratorAlgorithmConfig.densify_enabled.

Module Contents#

pyfracval.densify.radial_compress(coords, radii, alpha)[source]#

Radially compress coordinates toward CM by factor alpha.

Parameters:

  • coords ((N, 3) particle positions)

  • radii ((N,) particle radii)

  • alpha (compression factor (< 1.0 moves particles inward))

Return type:

Compressed coordinates, shape (N, 3)

pyfracval.densify.resolve_overlaps(coords, radii, tol_ov=0.0001, max_iters=50, push_fraction=0.5, patience=10, rng=None)[source]#

Iteratively resolve overlapping particle pairs.

Parameters:

  • coords ((N, 3) particle positions)

  • radii ((N,) particle radii)

  • tol_ov (maximum allowed fractional overlap)

  • max_iters (maximum resolution iterations)

  • push_fraction (fraction of overlap to push apart each step)

  • patience (stop after this many non-improving iterations)

  • rng (random number generator for jitter)

Return type:

(resolved_coords, success, n_iters)

pyfracval.densify.voronoi_local_density(coords)[source]#

Compute local number density from Voronoi cell volumes.

Uses scipy.spatial.Voronoi for tessellation. Volume is approximated as the volume of the circumscribed sphere of each Voronoi region (correct for convex polyhedra).

Parameters:

coords ((N, 3) particle positions)

Returns:

local_density

Return type:

(N,) array of local number densities (1/volume)

pyfracval.densify.voronoi_migrate_step(coords, radii, rg_target, step_fraction=0.02)[source]#

One step of Voronoi-guided migration.

Moves particles in under-dense regions (high Voronoi volume / low density) toward the center of mass, proportional to their local under-density.

Parameters:

  • coords ((N, 3) particle positions)

  • radii ((N,) particle radii)

  • rg_target (target radius of gyration)

  • step_fraction (fraction of CM-to-particle distance to move each step)

Return type:

(updated_coords, current_rg)

pyfracval.densify.densify_aggregate(coords, radii, target_df, target_kf, tol_ov=0.0001, max_push_iters=50, max_densify_iters=20, push_fraction=0.5, push_patience=10, rg_rtol=0.02, method='radial', rng=None)[source]#

Densify an aggregate from its current Df toward target Df.

Parameters:

  • coords ((N, 3) particle positions (from CCA at source Df))

  • radii ((N,) particle radii)

  • target_df (target fractal dimension)

  • target_kf (target fractal prefactor)

  • tol_ov (maximum allowed fractional overlap during resolution)

  • max_push_iters (max overlap resolution iterations per densification step)

  • max_densify_iters (max densification iterations)

  • push_fraction (fraction of overlap to push apart each step)

  • push_patience (stop push-apart after this many stagnant iterations)

  • rg_rtol (relative tolerance on Rg target)

  • method ("radial" for radial compression, "voronoi" for Voronoi-guided)

  • rng (random number generator)

Return type:

(densified_coords, densified_radii, success)