pyfracval.cca_agg
=================

.. py:module:: pyfracval.cca_agg

.. autoapi-nested-parse::

   Implements the Cluster-Cluster Aggregation (CCA) algorithm.





Module Contents
---------------

.. py:class:: CCAggregator(initial_coords, initial_radii, initial_i_orden, n_total, df, kf, tol_ov, ext_case)

   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 :cite:p:`Moran2019FracVAL`. Includes overlap checking
   and rotation (`_cca_reintento`) during sticking.

   :param initial_coords: Nx3 array containing coordinates of all particles from all subclusters.
   :type initial_coords: np.ndarray
   :param initial_radii: N array containing radii corresponding to `initial_coords`.
   :type initial_radii: np.ndarray
   :param initial_i_orden: Mx3 array [[start, end, count], ...] defining the subclusters within
                           the initial coordinates and radii arrays.
   :type initial_i_orden: np.ndarray
   :param n_total: Total number of primary particles (N).
   :type n_total: int
   :param df: Target fractal dimension for the final aggregate.
   :type df: float
   :param kf: Target fractal prefactor for the final aggregate.
   :type kf: float
   :param tol_ov: Maximum allowable overlap fraction between particles during sticking.
   :type tol_ov: float
   :param ext_case: Flag (0 or 1) controlling the geometric criteria used in CCA
                    candidate selection (`_cca_select_candidates`) and sticking
                    (`_cca_sticking_v1`). See :cite:p:`Moran2019FracVAL` Appendix C.
   :type ext_case: int

   .. attribute:: N

      Total number of primary particles.

      :type: int

   .. attribute:: df, kf, tol_ov, ext_case

      Stored simulation parameters.

      :type: float/int

   .. attribute:: coords, radii

      Current coordinates and radii, updated after each iteration.

      :type: np.ndarray

   .. attribute:: i_orden

      Current cluster index map, updated after each iteration.

      :type: np.ndarray

   .. attribute:: i_t

      Current number of clusters remaining.

      :type: int

   .. attribute:: not_able_cca

      Flag indicating if the CCA process failed.

      :type: bool


   .. py:method:: run_cca()

      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).
      :rtype: tuple[np.ndarray, np.ndarray] | None