cratepy.clustering.clusteringphase.HAACRMP

class HAACRMP(mat_phase, cluster_data_matrix, n_clusters, adaptivity_type)

Bases: ACRMP

Hierarchical Agglomerative Adaptive Cluster-Reduced Material Phase.

_clustering_type

Type of cluster-reduced material phase.

Type:

str

_linkage_matrix

Linkage matrix associated with the hierarchical agglomerative clustering (numpy.ndarray of shape (n_phase_voxels - 1, 4)).

Type:

numpy.ndarray (2d)

_cluster_node_map

Tree node id (item, int) associated with each cluster label (key, str).

Type:

dict

_adaptive_step

Counter of adaptive clustering steps, with 0 associated with the base clustering.

Type:

int

_adapt_split_factor

Adaptive clustering split factor. The adaptive clustering split factor must be contained between 0 and 1 (included). The lower bound (0) enforces a single split, i.e., 2 new clusters, while the upper bound (1) is associated with a maximum defined number of new voxels.

Type:

float

_threshold_n_clusters

Threshold number of adaptive material phase number of clusters. Once this threshold is surpassed, the adaptive procedures of the adaptive material phase are deactivated.

Type:

int

_is_dynamic_split_factor

True if adaptive clustering split factor is to be computed dynamically. Otherwise, the adaptive clustering split factor is always set equal to _adapt_split_factor.

Type:

bool

max_label

Clustering maximum label.

Type:

int

cluster_labels

Material phase cluster labels (numpy.ndarray[int] of shape (n_phase_voxels,)).

Type:

numpy.ndarray (1d)

adaptive_time

Total amount of time (s) spent in the adaptive procedures.

Type:

float

adaptivity_lock

True if the adaptive procedures are deactivated, False otherwise.

Type:

bool

perform_base_clustering(self, base_clustering_scheme, min_label=0)

Perform HAACRMP base clustering.

perform_adaptive_clustering(self, target_clusters, target_clusters_data, adaptive_clustering_scheme=None, min_label=0)

Perform HAACRMP adaptive clustering step.

add_to_tree_node_list(node_list, node)

Add node to tree node list and sort by descending linkage distance.

_check_adaptivity_lock(self)

Check ACRMP adaptivity locking conditions.

print_adaptive_clustering(self, adaptive_clustering_map, adaptive_tree_node_map)

get_valid_clust_algs()

Get valid clustering algorithms to compute the CRMP.

get_n_clusters(self)

Get current number of clusters.

get_clustering_type(self)

Get cluster-reduced material phase adaptivity type.

get_adaptivity_type_parameters()

Get ACRMP mandatory and optional adaptivity type parameters.

_set_adaptivity_type_parameters(self, adaptivity_type)

Set clustering adaptivity parameters.

get_adaptive_output(self)

Get adaptivity metrics for clustering adaptivity output.

Constructor.

Parameters:

• mat_phase (str) – Material phase label.

• cluster_data_matrix (numpy.ndarray (2d)) – Data matrix (numpy.ndarray of shape (n_phase_voxels, n_features_dims)) containing the clustering features data to perform the material phase cluster analyses.

• n_clusters (int) – Number of material phase clusters.

• adaptivity_type (dict) – Clustering adaptivity parameters.

List of Public Methods

add_to_tree_node_list	Add node to tree node list and sort by descending linkage distance.
get_adaptive_output	Get adaptivity metrics for clustering adaptivity output.
get_adaptivity_type_parameters	Get ACRMP mandatory and optional adaptivity type parameters.
get_clustering_type	Get cluster-reduced material phase adaptivity type.
get_n_clusters	Get current number of clusters.
get_valid_clust_algs	Get valid clustering algorithms to compute the CRMP.
perform_adaptive_clustering	Perform HAACRMP adaptive clustering step.
perform_base_clustering	Perform HAACRMP base clustering.
print_adaptive_clustering	Print hierarchical adaptive clustering report (validation).

Methods

__init__(mat_phase, cluster_data_matrix, n_clusters, adaptivity_type)

Constructor.

Parameters:

• mat_phase (str) – Material phase label.

• cluster_data_matrix (numpy.ndarray (2d)) – Data matrix (numpy.ndarray of shape (n_phase_voxels, n_features_dims)) containing the clustering features data to perform the material phase cluster analyses.

• n_clusters (int) – Number of material phase clusters.

• adaptivity_type (dict) – Clustering adaptivity parameters.

_check_adaptivity_lock()

Check ACRMP adaptivity locking conditions.

Check conditions that may deactivate the adaptive procedures in the ACRMP. Once the ACRMP adaptivity is locked, it is treated as a SCRMP for the remainder of the problem numerical solution.

static _dynamic_split_factor(ref_split_factor, adapt_trigger_ratio, magnitude, dynamic_amp=0)

Compute dynamic adaptive clustering split factor.

A detailed description of the dynamic adaptive clustering split factor can be found in Ferreira et. al (2022) [1].

[1]

Ferreira, B.P., Andrade Pires, F.M. and Bessa, M.A. (2022). Adaptivity for clustering-based reduced-order modeling of localized history-dependent phenomena. Comp Methods Appl M, 393 (see here)

---

Parameters:

• ref_split_factor (float) – Reference (centered) adaptive clustering split factor. The adaptive clustering split factor must be contained between 0 and 1 (included). The lower bound (0) enforces a single split, while the upper bound (1) performs the maximum number splits of each cluster (leading to single-voxel clusters).

• adapt_trigger_ratio (float) – Threshold associated with the adaptivity trigger condition.

• magnitude (float) – Difference between cluster ratio and adaptive trigger ratio. Given that the cluster ratio ranges between 0 and 1 and only clusters with a ratio greater or equal than the adaptive trigger ratio are targeted, the magnitude ranges between 0 and 1 - trigger ratio.

• dynamic_amp (float, default=0) – Dynamic split factor amplitude centered around the reference adaptive clustering split factor.

Returns:

adapt_split_factor – Adaptive clustering split factor. The adaptive clustering split factor must be contained between 0 and 1 (included). The lower bound (0) enforces a single split, i.e., 2 new clusters, while the upper bound (1) is associated with a maximum defined number of new voxels.

Return type:

float

_set_adaptivity_type_parameters(adaptivity_type)

Set clustering adaptivity parameters.

Parameters:

adaptivity_type (dict) – Clustering adaptivity parameters.

static _update_cluster_labels(labels, min_label=0)

Update cluster labels starting with the provided minimum label.

Parameters:

• labels (numpy.ndarray (1d)) – Cluster labels (numpy.ndarray[int] of shape (n_items,)).

• min_label (int, default=0) – Minimum cluster label.

Returns:

• new_labels (numpy.ndarray (1d)) – Updated cluster labels (numpy.ndarray[int] of shape (n_items,)).

• max_label (int) – Maximum cluster label.

static add_to_tree_node_list(node_list, node)

Add node to tree node list and sort by descending linkage distance.

Parameters:

• node_list (list[ClusterNode]) – List of ClusterNode instances.

• node (ClusterNode) – ClusterNode to be added to list[ClusterNode].

get_adaptive_output()

Get adaptivity metrics for clustering adaptivity output.

Returns:

adaptivity_output – List containing the adaptivity metrics associated with the clustering adaptivity output file.

Return type:

list

static get_adaptivity_type_parameters()

Get ACRMP mandatory and optional adaptivity type parameters.

Besides returning the ACRMP mandatory and optional adaptivity type parameters, this method establishes the default values for the optional parameters.

---

Returns:

• mandatory_parameters (dict) – Mandatory adaptivity type parameters (str) and associated type (item, type).

• optional_parameters (dict) – Optional adaptivity type parameters (key, str) and associated default value (item).

get_clustering_type()

Get cluster-reduced material phase adaptivity type.

Returns:

clustering_type – Type of cluster-reduced material phase.

Return type:

str

get_n_clusters()

Get current number of clusters.

Returns:

n_clusters – Number of material phase clusters.

Return type:

int

static get_valid_clust_algs()

Get valid clustering algorithms to compute the CRMP.

Returns:

clust_algs – Clustering algorithms identifiers (str).

Return type:

list[str]

perform_adaptive_clustering(target_clusters, target_clusters_data, adaptive_clustering_scheme=None, min_label=0)

Perform HAACRMP adaptive clustering step.

Refine the provided target clusters by splitting them according to the hierarchical agglomerative tree, prioritizing child nodes by descending order of linkage distance.

---

Parameters:

• target_clusters (list[int]) – List with the labels (int) of clusters to be adapted.

• target_clusters_data (dict) – For each target cluster (key, str), store dictionary (item, dict) containing cluster associated parameters relevant for the adaptive procedures.

• adaptive_clustering_scheme (dict) – Prescribed adaptive clustering scheme (item, numpy.ndarray of shape (n_clusterings, 3)) for each material phase (key, str). Each row is associated with a unique clustering characterized by a clustering algorithm (col 1, int), a list of features (col 2, list[int]) and a list of the features data matrix’ indexes (col 3, list[int]).

• min_label (int, default=0) – Minimum cluster label.

Returns:

• adaptive_clustering_map (dict) – List of new cluster labels (item, list[int]) resulting from the adaptivity of each target cluster (key, str).

• adaptive_tree_node_map (dict) – List of new cluster tree node ids (item, list[int]) resulting from the split of each target cluster tree node id (key, str). Validation purposes only (not returned otherwise).

perform_base_clustering(base_clustering_scheme, min_label=0)

Perform HAACRMP base clustering.

Parameters:

• base_clustering_scheme (dict) – Prescribed base clustering scheme (item, numpy.ndarray of shape (n_clusterings, 3)) for each material phase (key, str). Each row is associated with a unique clustering characterized by a clustering algorithm (col 1, int), a list of features (col 2, list[int]) and a list of the features data matrix’ indexes (col 3, list[int]).

• min_label (int, default=0) – Minimum cluster label.

print_adaptive_clustering(adaptive_clustering_map, adaptive_tree_node_map)

Print hierarchical adaptive clustering report (validation).