Quickstart Guide

Get started with AutoFragment in 5 minutes! This guide shows you how to install the library and run your first molecular fragmentation.

Installation

Install AutoFragment using pip:

pip install autofragment

For development or additional features:

pip install autofragment[all]

Optional Dependencies

Some features require additional packages:

# For balanced (constrained) clustering
pip install autofragment[balanced]

# For graph-based features
pip install autofragment[graph]

# For biological systems (mmCIF parsing via gemmi)
pip install autofragment[bio]

# For materials science (periodic systems)
pip install autofragment[matsci]

Your First Fragmentation

Load a System

from autofragment import io

# From XYZ file
system = io.read_xyz("molecule.xyz")

# From PDB file (via FormatRegistry)
from autofragment.io.writers import FormatRegistry
system = FormatRegistry.read("protein.pdb")

# Print basic info
print(f"Loaded {system.n_atoms} atoms")
print(f"Bonds: {system.n_bonds}")

Fragment the System

from autofragment import MolecularPartitioner

# Create a partitioner with target number of fragments
partitioner = MolecularPartitioner(n_fragments=4)

# Fragment the system
tree = partitioner.partition(system)

# Inspect results
print(f"Created {len(tree.fragments)} fragments")
for i, frag in enumerate(tree.fragments):
    print(f"  Fragment {i}: {frag.n_atoms} atoms")

Examine Fragment Details

for fragment in tree.fragments:
    print(f"Fragment: {fragment.n_atoms} atoms")
    print(f"  Charge: {fragment.molecular_charge}")
    print(f"  Multiplicity: {fragment.molecular_multiplicity}")
    print(f"  Elements: {set(fragment.symbols)}")

Export to a Quantum Chemistry Program

GAMESS (FMO)

from autofragment.io import write_gamess_fmo

write_gamess_fmo(
    tree.fragments,
    "output.inp",
    method="MP2",
    basis="6-31G*",
)

Psi4

from autofragment.io import write_psi4_sapt

write_psi4_sapt(
    tree.fragments,
    "output.dat",
    method="b3lyp",
    basis="cc-pVDZ",
)

XYZ (Generic)

from autofragment.io import write_xyz_fragments

write_xyz_fragments(tree.fragments, "fragments.xyz")

Command-Line Interface

AutoFragment also provides a CLI:

# Basic fragmentation
autofragment single --input molecule.xyz --output partitioned.json --n-fragments 4

# Batch mode with consistent labeling
autofragment batch --reference ref.xyz --input-dir ./trajectory/ --output-dir ./partitioned/ --n-fragments 4

# Biological systems (mmCIF)
autofragment bio --input protein.cif --output partitioned.json

# See all options
autofragment --help

Common Workflows

Water Cluster (MBE)

from autofragment import io, MolecularPartitioner

# Load water cluster
cluster = io.read_xyz("water20.xyz")

# Fragment into groups of waters
partitioner = MolecularPartitioner(n_fragments=4, method="kmeans")
tree = partitioner.partition(cluster)

print(f"Fragments: {len(tree.fragments)}")

Tiered Hierarchical Fragmentation

For large systems, use tiered partitioning to create a hierarchy of fragments:

from autofragment import MolecularPartitioner

partitioner = MolecularPartitioner(
    tiers=2, n_primary=4, n_secondary=4, method="kmeans"
)
tree = partitioner.partition(cluster)

print(f"Primary fragments: {tree.n_primary}")
for pf in tree.fragments:
    print(f"  {pf.id}: {len(pf.fragments)} sub-fragments, {pf.n_atoms} atoms")

Protein Fragmentation

from autofragment import BioPartitioner

# Partition from mmCIF directly
partitioner = BioPartitioner()
tree = partitioner.partition_file("1ubq.cif")

Configuration

Clustering Methods

AutoFragment supports several clustering methods:

from autofragment import MolecularPartitioner

# Standard k-means (default, no extra deps)
partitioner = MolecularPartitioner(n_fragments=4, method="kmeans")

# Constrained k-means for balanced fragments (requires autofragment[balanced])
partitioner = MolecularPartitioner(n_fragments=4, method="kmeans_constrained")

# Agglomerative clustering
partitioner = MolecularPartitioner(n_fragments=4, method="agglomerative")

# Spectral clustering
partitioner = MolecularPartitioner(n_fragments=4, method="spectral")

Next Steps

Now that you’ve run your first fragmentation, explore more:

Water Clusters Tutorial: Complete MBE workflow for water clusters
Protein Fragmentation: Fragment proteins with biological rules
Materials Science Guide: Work with periodic systems
Output Formats: Export to different QC programs

Getting Help

Documentation: Documentation Home
Development Guide: Development

Troubleshooting

Common Issues

Import Error: Make sure autofragment is installed in your environment:

pip show autofragment

Missing Optional Features: Install optional dependencies:

pip install autofragment[all]

File Not Found: Use absolute paths or check working directory:

import os
print(os.getcwd())