autofragment.MolecularPartitioner

class autofragment.MolecularPartitioner(n_fragments=4, method='kmeans', random_state=42, strict_balanced=None, topology_refine=False, topology_mode='graph', topology_hops=1, topology_layers=1, topology_k_per_layer=1, topology_bond_policy='infer', tiers=None, n_primary=None, n_secondary=None, n_tertiary=None, init_strategy=None, init_strategy_primary=None, init_strategy_secondary=None, init_strategy_tertiary=None)[source]

Partitioner for water clusters and similar molecular systems.

Supports both flat partitioning (default) and tiered hierarchical partitioning (2-tier and 3-tier).

Parameters:

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

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

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

  • strict_balanced (bool, optional) – If True, validate equal cluster sizes. Default is True for kmeans_constrained, False otherwise.

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

  • 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 | ndarray | dict | None, optional) – Default seeding strategy for all tiers / flat mode.

  • init_strategy_primary (str | ndarray | dict | None, optional) – Override seeding strategy for primary (tier-1) clustering.

  • init_strategy_secondary (str | ndarray | dict | None, optional) – Override seeding strategy for secondary (tier-2) clustering.

  • init_strategy_tertiary (str | ndarray | dict | None, optional) – Override seeding strategy for tertiary (tier-3) clustering.

  • topology_refine (bool)

  • topology_mode (SelectionMode)

  • topology_hops (int)

  • topology_layers (int)

  • topology_k_per_layer (int)

  • topology_bond_policy (BondPolicy)

Examples

Flat mode:

>>> partitioner = MolecularPartitioner(n_fragments=2, method="kmeans")
>>> tree = partitioner.partition(system)
>>> len(tree.fragments)
2

Tiered mode:

>>> partitioner = MolecularPartitioner(
...     tiers=2, n_primary=4, n_secondary=4
... )
>>> tree = partitioner.partition(system)
>>> tree.n_primary
4

See also

autofragment.partitioners.batch.BatchPartitioner

For processing multiple files.

autofragment.core.types.FragmentTree

The result object containing fragments.

__init__(n_fragments=4, method='kmeans', random_state=42, strict_balanced=None, topology_refine=False, topology_mode='graph', topology_hops=1, topology_layers=1, topology_k_per_layer=1, topology_bond_policy='infer', tiers=None, n_primary=None, n_secondary=None, n_tertiary=None, init_strategy=None, init_strategy_primary=None, init_strategy_secondary=None, init_strategy_tertiary=None)[source]

Initialize a new MolecularPartitioner instance.

Parameters:

Methods

__init__([n_fragments, method, ...])

Initialize a new MolecularPartitioner instance.

partition(system[, source_file])

Partition a chemical system into fragments.