rgpycrumbs.geom.detect_fragments

Detects molecular fragments in coordinate files using two distinct methodologies: 1. Geometric: Utilizes scaled covalent radii. 2. Bond Order: Employs GFN2-xTB semi-empirical calculations.

The tool supports fragment merging based on centroid proximity and batch processing for high-throughput computational chemistry workflows.

Usage for a single file: uv run python detect_fragments.py geometric your_file.xyz –multiplier 1.1 uv run python detect_fragments.py bond-order your_file.xyz –threshold 0.7 –min-dist 4.0

Usage for a directory (batch mode): uv run python detect_fragments.py batch ./your_folder/ –method geometric –min-dist 3.5

Attributes

cmap_name
tbliteinterface
DEFAULT_BOND_MULTIPLIER
DEFAULT_BOND_ORDER_THRESHOLD
SCALAR_BAR_ARGS
MIN_DIST_ATM

Classes

DetectionMethod

Available detection methodologies.

Functions

find_fragments_geometric(→ tuple[int, numpy.ndarray])
find_fragments_bond_order(→ tuple[int, numpy.ndarray, ...)	Analyze connectivity via the Wiberg Bond Order (WBO) matrix.
build_graph_and_find_components(→ tuple[int, ...)	Identify connected components using direct CSR sparse matrix construction.
merge_fragments_by_distance(→ tuple[int, numpy.ndarray])	Merges fragments with geometric centers closer than the specified distance.
visualize_with_pyvista(→ None)	Renders the molecular system with scalar-coded bond orders.
print_results(→ None)	Displays analysis results in a structured table.
main()	Fragment detection suite for physical chemistry simulations.
geometric(filename, multiplier, radius_type, min_dist, ...)	Executes geometric fragment detection.
bond_order(filename, method, threshold, charge, ...)	Execute fragment detection using quantum mechanical bond orders.
batch(directory, method, pattern, output, min_dist)	Processes directories and outputs CSV summaries.

Module Contents

rgpycrumbs.geom.detect_fragments.cmap_name = 'batlow'

rgpycrumbs.geom.detect_fragments.tbliteinterface

class rgpycrumbs.geom.detect_fragments.DetectionMethod

Bases: enum.StrEnum

Available detection methodologies.

GEOMETRIC = 'geometric'

BOND_ORDER = 'bond-order'

rgpycrumbs.geom.detect_fragments.DEFAULT_BOND_MULTIPLIER = 1.2

rgpycrumbs.geom.detect_fragments.DEFAULT_BOND_ORDER_THRESHOLD = 0.8

rgpycrumbs.geom.detect_fragments.SCALAR_BAR_ARGS

rgpycrumbs.geom.detect_fragments.MIN_DIST_ATM = 0.0001

rgpycrumbs.geom.detect_fragments.find_fragments_geometric(atoms: ase.atoms.Atoms, bond_multiplier: float, radius_type: str = 'natural') → tuple[int, numpy.ndarray]

rgpycrumbs.geom.detect_fragments.find_fragments_bond_order(atoms: ase.atoms.Atoms, threshold: float, charge: int, multiplicity: int, method: str = 'GFN2-xTB') → tuple[int, numpy.ndarray, numpy.ndarray, numpy.ndarray]

Analyze connectivity via the Wiberg Bond Order (WBO) matrix. Calculate electronic structure using the specified xTB level.

rgpycrumbs.geom.detect_fragments.build_graph_and_find_components(num_atoms: int, row_indices: numpy.ndarray | list[int], col_indices: numpy.ndarray | list[int]) → tuple[int, numpy.ndarray]

Identify connected components using direct CSR sparse matrix construction.

This function avoids Python list overhead by passing interaction indices directly to the SciPy sparse engine.

rgpycrumbs.geom.detect_fragments.merge_fragments_by_distance(atoms: ase.atoms.Atoms, n_components: int, labels: numpy.ndarray, min_dist: float) → tuple[int, numpy.ndarray]

Merges fragments with geometric centers closer than the specified distance.

rgpycrumbs.geom.detect_fragments.visualize_with_pyvista(atoms: ase.atoms.Atoms, method: DetectionMethod, bond_data: float | numpy.ndarray, nonbond_cutoff: float = 0.05, bond_threshold: float = 0.8, radius_type: str = 'natural') → None

Renders the molecular system with scalar-coded bond orders.

rgpycrumbs.geom.detect_fragments.print_results(console: rich.console.Console, atoms: ase.atoms.Atoms, n_components: int, labels: numpy.ndarray) → None

Displays analysis results in a structured table.

rgpycrumbs.geom.detect_fragments.main()

Fragment detection suite for physical chemistry simulations.

rgpycrumbs.geom.detect_fragments.geometric(filename, multiplier, radius_type, min_dist, visualize)

Executes geometric fragment detection.

rgpycrumbs.geom.detect_fragments.bond_order(filename, method, threshold, charge, multiplicity, min_dist, visualize)

Execute fragment detection using quantum mechanical bond orders.

rgpycrumbs.geom.detect_fragments.batch(directory, method, pattern, output, min_dist)

Processes directories and outputs CSV summaries.