autofragment.BatchPartitioner

class autofragment.BatchPartitioner(reference_tree, reference_molecules, reference_labels, *, n_fragments, metric='rmsd', hybrid_alpha=0.5, align=False, centroid_threshold=2.0, rmsd_threshold=2.5, method='kmeans_constrained', tiers=None, n_primary=None, n_secondary=None, n_tertiary=None)[source]

Partitioner for multiple files with consistent labeling.

This partitioner uses a reference structure to establish fragment labels, then applies those labels to additional structures by matching molecules based on their positions.

Parameters:

  • reference_tree (FragmentTree) – Reference fragment tree (from MolecularPartitioner).

  • reference_molecules (ChemicalSystem | Sequence[Molecule]) – Reference system used to create the tree.

  • reference_labels (Sequence) – Labels from reference partitioning.

  • metric (str, optional) – Distance metric for matching: “centroid”, “rmsd”, or “hybrid”. Default is “rmsd”.

  • hybrid_alpha (float, optional) – Weight for centroid in hybrid metric. Default is 0.5.

  • align (bool, optional) – If True, apply Kabsch alignment before matching. Default is False.

  • centroid_threshold (float, optional) – Quality threshold for centroid distance. Default is 2.0.

  • rmsd_threshold (float, optional) – Quality threshold for RMSD. Default is 2.5.

  • n_fragments (int)

  • method (str)

  • tiers (Optional[int])

  • n_primary (Optional[int])

  • n_secondary (Optional[int])

  • n_tertiary (Optional[int])

Examples

>>> partitioner = MolecularPartitioner(n_fragments=4)
>>> reference = read_xyz("reference.xyz")
>>> ref_tree = partitioner.partition(reference)
>>>
>>> batch = BatchPartitioner.from_partitioner(
...     partitioner, reference, metric="rmsd", align=True
... )
>>> for filepath in trajectory_files:
...     result = batch.partition_file(filepath)
...     result.to_json(f"output/{filepath.stem}.json")
__init__(reference_tree, reference_molecules, reference_labels, *, n_fragments, metric='rmsd', hybrid_alpha=0.5, align=False, centroid_threshold=2.0, rmsd_threshold=2.5, method='kmeans_constrained', tiers=None, n_primary=None, n_secondary=None, n_tertiary=None)[source]

Initialize a new BatchPartitioner instance.

Parameters:

  • reference_tree (FragmentTree)

  • reference_molecules (Sequence[Molecule])

  • reference_labels (Sequence)

  • n_fragments (int)

  • metric (str)

  • hybrid_alpha (float)

  • align (bool)

  • centroid_threshold (float)

  • rmsd_threshold (float)

  • method (str)

  • tiers (int | None)

  • n_primary (int | None)

  • n_secondary (int | None)

  • n_tertiary (int | None)

Methods

__init__(reference_tree, ...[, metric, ...])

Initialize a new BatchPartitioner instance.

from_partitioner(partitioner, ...[, metric, ...])

Create a BatchPartitioner from a MolecularPartitioner.

partition(system[, source_file, force])

Partition a system using reference labels.

partition_file(filepath[, force, xyz_units])

Partition molecules from a file.

partition_files(filepaths, *[, force, ...])

Partition multiple XYZ files in parallel.

partition_many(systems, *[, source_files, ...])

Partition multiple systems in parallel.