pyfracval.pca_subclusters#

Divides initial particles into subclusters using PCA.

Module Contents#

class pyfracval.pca_subclusters.Subclusterer(/, **data)[source]#

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

Parameters:

  • initial_radii (np.ndarray) – 1D array of all initial primary particle radii.

  • df (float) – Target fractal dimension (passed to PCAggregator).

  • kf (float) – Target fractal prefactor (passed to PCAggregator).

  • tol_ov (float) – Overlap tolerance (passed to PCAggregator).

  • n_subcl_percentage (float) – Target fraction of N used to determine the approximate size of each subcluster. Actual sizes may vary.

N[source]#

Total number of particles.

Type:

int

all_coords[source]#

Nx3 array storing coordinates of all particles after PCA subclustering.

Type:

np.ndarray

all_radii[source]#

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

i_orden[source]#

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

number_clusters[source]#

The number of subclusters generated.

Type:

int

not_able_pca[source]#

Flag indicating if any PCA run for a subcluster failed.

Type:

bool

number_clusters_processed[source]#

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

Type:

int

model_config[source]#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(__context)[source]#

Override this method to perform additional initialization after __init__ and model_construct. This is useful if you want to do some validation that requires the entire model to be initialized.

run_subclustering()[source]#

Perform the subclustering process.

Determines subcluster sizes, then runs PCAggregator on each subset of radii — in parallel (via multiprocessing.Pool) when self.algorithm_config.parallel_subclusters is True and the number of subclusters exceeds self.algorithm_config.parallel_subclusters_min_count, otherwise sequentially.

Returns:

True if all subclusters were generated successfully, False otherwise. Sets self.not_able_pca to True on failure.

Return type:

bool

get_results()[source]#

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.

Return type:

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