Cluster Analysis

Overview

Cluster Analysis groups atoms into connected components using a cutoff-based neighbor graph. In practical terms, it answers a simple question: which atoms belong to the same connected aggregate under the distance rule you chose?

That makes it useful for precipitates, fragments, void-related shells, molecular aggregates, and any workflow where connectivity matters more than crystal identity.

Parameters

Parameter	Type	Default	Description
`cutoff`	`float`	`3.2`	Cutoff radius used to define connectivity.
`sortBySize`	`bool`	`true`	Sort clusters by size in descending order.
`unwrap`	`bool`	`false`	Unwrap particle coordinates inside each cluster.
`centersOfMass`	`bool`	`false`	Compute cluster centers with uniform weights.
`radiusOfGyration`	`bool`	`false`	Compute radii and tensors of gyration with uniform weights.

Practical notes

The current implementation is cutoff-based. Bond-topology mode is not available in the runtime path used by this plugin.
Center-of-mass and gyration outputs are purely geometric here; they do not use atom-type-specific masses.
When enabled, unwrapped positions are reported per atom so you can inspect cluster geometry across periodic boundaries.

Output

`{outputBase}_cluster_analysis.msgpack`

type Vec3 = [float, float, float];
type GyrationTensor = [float, float, float, float, float, float];

interface Cluster {
    cluster_id: int;
    size: int;
    center?: Vec3;
    radius_of_gyration?: float;
    gyration_tensor?: GyrationTensor;
}

interface PerAtomProperties {
    id: int;
    cluster: int;
    pos_unwrapped?: Vec3;
}

interface ClusterAnalysisOutput {
    main_listing: {
        total_atoms: int;
        clusters: int;
        largest_cluster_size: int;
        has_zero_weight_cluster: boolean;
    };
    sub_listings: {
        clusters: Cluster[];
    };
    "per-atom-properties": PerAtomProperties[];
}