pyfracval.cca_agg#

Implements the Cluster-Cluster Aggregation (CCA) algorithm.

Module Contents#

class pyfracval.cca_agg.CCAggregator(initial_coords, initial_radii, initial_i_orden, n_total, df, kf, tol_ov, ext_case)[source]#

Performs Cluster-Cluster Aggregation (CCA).

Takes pre-generated subclusters (defined by coordinates, radii, and the i_orden index map) and iteratively aggregates them in pairs. The pairing and sticking process attempts to preserve the target fractal dimension (Df) and prefactor (kf) using the Gamma_pc method derived from [Morán et al., 2019]. Includes overlap checking and rotation (_cca_reintento) during sticking.

Parameters:

  • initial_coords (np.ndarray) – Nx3 array containing coordinates of all particles from all subclusters.

  • initial_radii (np.ndarray) – N array containing radii corresponding to initial_coords.

  • initial_i_orden (np.ndarray) – Mx3 array [[start, end, count], …] defining the subclusters within the initial coordinates and radii arrays.

  • n_total (int) – Total number of primary particles (N).

  • df (float) – Target fractal dimension for the final aggregate.

  • kf (float) – Target fractal prefactor for the final aggregate.

  • tol_ov (float) – Maximum allowable overlap fraction between particles during sticking.

  • ext_case (int) – Flag (0 or 1) controlling the geometric criteria used in CCA candidate selection (_cca_select_candidates) and sticking (_cca_sticking_v1). See [Morán et al., 2019] Appendix C.

N[source]#

Total number of primary particles.

Type:

int

df, kf, tol_ov, ext_case

Stored simulation parameters.

Type:

float/int

coords, radii

Current coordinates and radii, updated after each iteration.

Type:

np.ndarray

i_orden[source]#

Current cluster index map, updated after each iteration.

Type:

np.ndarray

i_t[source]#

Current number of clusters remaining.

Type:

int

not_able_cca[source]#

Flag indicating if the CCA process failed.

Type:

bool

run_cca()[source]#

Run the complete CCA process until only one cluster remains.

Repeatedly calls _run_iteration which performs pairing and sticking for the current set of clusters. Updates the internal state (coords, radii, i_orden, i_t) after each iteration.

Returns:

A tuple containing:

  • final_coords (np.ndarray): Nx3 coordinates of the final aggregate.

  • final_radii (np.ndarray): N radii of the final aggregate.

Returns None if the aggregation process fails at any stage (sets self.not_able_cca to True).

Return type:

tuple[np.ndarray, np.ndarray] | None