pyfracval.pca_subclusters
=========================

.. py:module:: pyfracval.pca_subclusters

.. autoapi-nested-parse::

   Divides initial particles into subclusters using PCA.





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

.. py:class:: Subclusterer(initial_radii, df, kf, tol_ov, n_subcl_percentage)

   Handles division of particles into subclusters using PCA.

   Takes a full set of initial particle radii, determines appropriate
   subcluster sizes, and runs the `PCAggregator` on each subset of radii
   to generate initial cluster structures. These subclusters are intended
   as input for subsequent Cluster-Cluster Aggregation (CCA).

   :param initial_radii: 1D array of all initial primary particle radii.
   :type initial_radii: np.ndarray
   :param df: Target fractal dimension (passed to `PCAggregator`).
   :type df: float
   :param kf: Target fractal prefactor (passed to `PCAggregator`).
   :type kf: float
   :param tol_ov: Overlap tolerance (passed to `PCAggregator`).
   :type tol_ov: float
   :param n_subcl_percentage: Target fraction of N used to determine the approximate
                              size of each subcluster. Actual sizes may vary.
   :type n_subcl_percentage: float

   .. attribute:: N

      Total number of particles.

      :type: int

   .. attribute:: all_coords

      Nx3 array storing coordinates of all particles after PCA subclustering.

      :type: np.ndarray

   .. attribute:: all_radii

      N array storing radii of all particles (should match initial radii order
      if PCA doesn't reorder, but uses radii from PCA output).

      :type: np.ndarray

   .. attribute:: i_orden

      Mx3 array defining the start index, end index (inclusive), and count
      for each generated subcluster within the `all_coords`/`all_radii` arrays.
      None until `run_subclustering` is successful.

      :type: np.ndarray | None

   .. attribute:: number_clusters

      The number of subclusters generated.

      :type: int

   .. attribute:: not_able_pca

      Flag indicating if any PCA run for a subcluster failed.

      :type: bool

   .. attribute:: number_clusters_processed

      Index of the last subcluster processed (useful for error reporting).

      :type: int


   .. py:method:: run_subclustering()

      Perform the subclustering process.

      Determines subcluster sizes, then iterates through subsets of the
      initial radii, running `PCAggregator` for each subset. Stores the
      resulting coordinates and radii contiguously and updates `i_orden`.

      :returns: True if all subclusters were generated successfully, False otherwise.
                Sets `self.not_able_pca` to True on failure.
      :rtype: bool



   .. py:method:: get_results()

      Return the results of the subclustering process.

      :returns:

                A tuple containing:
                    - number_clusters (int): The intended number of clusters.
                    - not_able_pca (bool): Flag indicating if any PCA failed.
                    - combined_data (np.ndarray | None): Nx4 array [X, Y, Z, R] of all
                      particles, or None on failure.
                    - i_orden (np.ndarray | None): Mx3 array describing subcluster
                      indices, or None on failure.
                    - final_radii (np.ndarray | None): N array of radii corresponding
                      to `combined_data`, or None on failure.
      :rtype: tuple[int, bool, np.ndarray | None, np.ndarray | None, np.ndarray | None]