pyfracval.pca_agg
=================

.. py:module:: pyfracval.pca_agg

.. autoapi-nested-parse::

   Implements Particle-Cluster Aggregation (PCA) for initial subclusters.





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

.. py:class:: PCAggregator(initial_radii, df, kf, tol_ov)

   Performs Particle-Cluster Aggregation (PCA).

   Builds a single cluster by sequentially adding individual primary
   particles (monomers) to a growing aggregate, attempting to match
   the target Df and kf via the Gamma_pc calculation at each step.
   Includes overlap checking and rotation to find valid placements.

   :param initial_radii: 1D array of radii for the primary particles to be aggregated.
   :type initial_radii: np.ndarray
   :param df: Target fractal dimension for the aggregate.
   :type df: float
   :param kf: Target fractal prefactor for the aggregate.
   :type kf: float
   :param tol_ov: Maximum allowable overlap fraction between particles.
   :type tol_ov: float

   .. attribute:: N

      Total number of particles to aggregate.

      :type: int

   .. attribute:: initial_mass

      Calculated initial masses corresponding to `initial_radii`.

      :type: np.ndarray

   .. attribute:: coords

      Nx3 array storing coordinates of particles as they are placed.

      :type: np.ndarray

   .. attribute:: radii

      N array storing radii of particles as they are placed.

      :type: np.ndarray

   .. attribute:: mass

      N array storing masses of particles as they are placed.

      :type: np.ndarray

   .. attribute:: n1

      Number of particles currently in the aggregate.

      :type: int

   .. attribute:: m1

      Mass of the current aggregate.

      :type: float

   .. attribute:: rg1

      Radius of gyration of the current aggregate.

      :type: float

   .. attribute:: cm

      3D center of mass of the current aggregate.

      :type: np.ndarray

   .. attribute:: r_max

      Maximum distance from CM to any particle center in the aggregate.

      :type: float

   .. attribute:: not_able_pca

      Flag indicating if the aggregation process failed.

      :type: bool


   .. py:method:: run()

      Run the complete PCA process for all N particles.

      Sequentially adds particles from index 2 to N-1. For each particle k,
      it calculates Gamma_pc, finds potential sticking partners (`candidates`)
      in the existing aggregate (0..k-1), potentially swaps particle k with
      an unused one if no candidates are found initially.

      It then attempts to stick particle k to each candidate partner,
      calculating an initial position based on sphere intersections defined
      by Gamma_pc. If overlap occurs, it rotates particle k around the
      intersection circle (`_reintento`) up to `max_rotations` times.

      If a non-overlapping position is found for any candidate, the particle
      is successfully added, and aggregate properties are updated. If all
      candidates and all rotations fail for a particle k, or if the initial
      search/swap fails, the aggregation stops, `not_able_pca` is set True,
      and None is returned.

      :returns: An Nx4 NumPy array [X, Y, Z, R] of the final aggregate if
                successful, otherwise None.
      :rtype: np.ndarray | None