Robust Structural Alignment

Structural Alignment API

The alignment module provides a robust mechanism for superimposing atomic structures.

Added in version 0.1.0.

It solves the “permutation-inversion” problem using the Iterative Rotations and Alignment (IRA) algorithm when available. If the ira library is missing or fails, it gracefully falls back to standard RMSD minimization (Procrustes analysis) via ase.

Key Features

Permutation Invariance

Correctly aligns molecules even if atom indices are scrambled (e.g., swapping two Hydrogens).

Hybrid Backend

Prioritizes libira for graph-matching but defaults to ase.build.minimize_rotation_and_translation for simple rigid rotations.

In-Place Modification

Modifies the target (mobile) Atoms object directly to match the reference.

Usage Example

from ase.build import molecule
from rgpycrumbs.geom.api.alignment import align_structure_robust, IRAConfig

# 1. Create a reference and a scrambled mobile structure
ref = molecule("H2O")
mobile = ref.copy()
mobile.rotate(90, 'z')
# Scramble indices: Swap H1 and H2
mobile = mobile[[0, 2, 1]]

# 2. Configure Alignment
config = IRAConfig(enabled=True, kmax=1.8)

# 3. Align
# 'mobile' is modified in-place to match 'ref'
result = align_structure_robust(ref, mobile, config)

print(f"Method used: {result.method}")
# Output: Method used: AlignmentMethod.IRA_PERMUTATION

API Reference

For developer details see rgpycrumbs.geom.api.alignment.