Fragment Detection¶

rgpycrumbs geom detect-fragments¶

Fragment detection suite for physical chemistry simulations.

Usage

rgpycrumbs geom detect-fragments [OPTIONS] COMMAND [ARGS]...

batch¶

Processes directories and outputs CSV summaries.

Usage

rgpycrumbs geom detect-fragments batch [OPTIONS] DIRECTORY

Options

--method <method>¶

Options:: geometric | bond-order

--pattern <pattern>¶

--output <output>¶

--min-dist <min_dist>¶

Arguments

DIRECTORY¶: Required argument

bond-order¶

Execute fragment detection using quantum mechanical bond orders.

Usage

rgpycrumbs geom detect-fragments bond-order [OPTIONS] FILENAME

Options

--method <method>¶

The xTB Hamiltonian level for calculation.

Options:: GFN2-xTB | GFN1-xTB | IPEA-xTB

--threshold <threshold>¶

--charge <charge>¶

--multiplicity <multiplicity>¶

--min-dist <min_dist>¶

--visualize¶

Arguments

FILENAME¶: Required argument

geometric¶

Executes geometric fragment detection.

Usage

rgpycrumbs geom detect-fragments geometric [OPTIONS] FILENAME

Options

--multiplier <multiplier>¶

--radius-type <radius_type>¶

Choose ‘natural’ for Cordero radii or ‘covalent’ for standard ASE radii.

Options:: natural | covalent

--min-dist <min_dist>¶: Merge threshold in Angstroms.

--visualize¶

Arguments

FILENAME¶: Required argument

Usage¶

To analyze molecular fragments using the geometric method, useful for standard organic molecules, the way ase visualizations work:

# Single file analysis
python -m rgpycrumbs.cli geom detect-fragments geometric molecule.xyz --multiplier 1.2

# Batch processing a directory
python -m rgpycrumbs.cli geom detect-fragments batch ./structures/ --output summary.csv

For systems with ambiguous bonding, like transition states or loosely bound complexes, use the Wiberg Bond Order method which requires tblite, described here:

python -m rgpycrumbs.cli geom detect-fragments bond-order complex.xyz --threshold 0.6

Python Example¶

You can also use the detection logic directly within Python scripts. This example demonstrates creating a water dimer in ASE and verifying it separates into two fragments.

from ase import Atoms
from ase.build import molecule
from rgpycrumbs.geom.detect_fragments import find_fragments_geometric

# 1. Construct a water dimer
# One water at the origin, another separated by 3.5 Angstroms
water_a = molecule("H2O")
water_b = molecule("H2O")
water_b.translate([3.5, 0, 0])

dimer = water_a + water_b

# 2. Detect fragments using geometric criteria (Cordero radii)
# A standard covalent bond check would treat these as separate.
n_frags, labels = find_fragments_geometric(dimer, bond_multiplier=1.2)

print(f"System contains {n_frags} fragments.")
print(f"Atom labels: {labels}")

# Expected Output:
# System contains 2 fragments.
# Atom labels: [0 0 0 1 1 1]

API Reference¶

For developer details and source code see rgpycrumbs.geom.detect_fragments.