autofragment.partition_xyz

autofragment.partition_xyz(filepath, *, n_fragments=4, method='kmeans', random_state=42, tiers=None, n_primary=None, n_secondary=None, n_tertiary=None, init_strategy=None)[source]

Partition a water cluster XYZ file into fragments.

This is a convenience function that combines reading the XYZ file and partitioning it in a single call. Supports both flat and tiered partitioning.

Parameters:

  • filepath (str) – Path to the XYZ file containing water molecules.

  • n_fragments (int, optional) – Number of fragments (flat mode). Default is 4.

  • method (str, optional) – Clustering method. Default is “kmeans”.

  • random_state (int, optional) – Random seed for reproducibility. Default is 42.

  • tiers (int, optional) – Number of hierarchy tiers (2 or 3). None = flat mode.

  • n_primary (int, optional) – Number of primary fragments (tiered mode).

  • n_secondary (int, optional) – Number of secondary fragments per primary (tiered mode).

  • n_tertiary (int, optional) – Number of tertiary fragments per secondary (3-tier mode).

  • init_strategy (str, optional) – K-means seeding strategy (e.g. “pca”, “axis”, “halfplane”, “radial”).

Returns:

Fragmentation result.

Return type:

FragmentTree

Examples

Flat mode:

>>> result = af.partition_xyz("water64.xyz", n_fragments=4)
>>> result.to_json("output.json")

Tiered mode:

>>> result = af.partition_xyz(
...     "water64.xyz", tiers=2, n_primary=4, n_secondary=4
... )