pyfracval.densify
=================

.. py:module:: pyfracval.densify

.. autoapi-nested-parse::

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

.. py:function:: radial_compress(coords, radii, alpha)

   Radially compress coordinates toward CM by factor alpha.

   :param coords:
   :type coords: (N, 3) particle positions
   :param radii:
   :type radii: (N,) particle radii
   :param alpha:
   :type alpha: compression factor (< 1.0 moves particles inward)

   :rtype: Compressed coordinates, shape (N, 3)


.. py:function:: resolve_overlaps(coords, radii, tol_ov = 0.0001, max_iters = 50, push_fraction = 0.5, patience = 10, rng = None)

   Iteratively resolve overlapping particle pairs.

   :param coords:
   :type coords: (N, 3) particle positions
   :param radii:
   :type radii: (N,) particle radii
   :param tol_ov:
   :type tol_ov: maximum allowed fractional overlap
   :param max_iters:
   :type max_iters: maximum resolution iterations
   :param push_fraction:
   :type push_fraction: fraction of overlap to push apart each step
   :param patience:
   :type patience: stop after this many non-improving iterations
   :param rng:
   :type rng: random number generator for jitter

   :rtype: (resolved_coords, success, n_iters)


.. py:function:: voronoi_local_density(coords)

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

   :param coords:
   :type coords: (N, 3) particle positions

   :returns: **local_density**
   :rtype: (N,) array of local number densities (1/volume)


.. py:function:: voronoi_migrate_step(coords, radii, rg_target, step_fraction = 0.02)

   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.

   :param coords:
   :type coords: (N, 3) particle positions
   :param radii:
   :type radii: (N,) particle radii
   :param rg_target:
   :type rg_target: target radius of gyration
   :param step_fraction:
   :type step_fraction: fraction of CM-to-particle distance to move each step

   :rtype: (updated_coords, current_rg)


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

   Densify an aggregate from its current Df toward target Df.

   :param coords:
   :type coords: (N, 3) particle positions (from CCA at source Df)
   :param radii:
   :type radii: (N,) particle radii
   :param target_df:
   :type target_df: target fractal dimension
   :param target_kf:
   :type target_kf: target fractal prefactor
   :param tol_ov:
   :type tol_ov: maximum allowed fractional overlap during resolution
   :param max_push_iters:
   :type max_push_iters: max overlap resolution iterations per densification step
   :param max_densify_iters:
   :type max_densify_iters: max densification iterations
   :param push_fraction:
   :type push_fraction: fraction of overlap to push apart each step
   :param push_patience:
   :type push_patience: stop push-apart after this many stagnant iterations
   :param rg_rtol:
   :type rg_rtol: relative tolerance on Rg target
   :param method:
   :type method: "radial" for radial compression, "voronoi" for Voronoi-guided
   :param rng:
   :type rng: random number generator

   :rtype: (densified_coords, densified_radii, success)