rgpycrumbs.geom.api.alignment

Attributes

ira_mod

Classes

IRAMatchInputs	Encapsulates the raw arrays required for an IRA graph match.
IRAMatchResults	Encapsulates the transformation outputs from the IRA algorithm.
IRAConfig	Configuration parameters for the Iterative Rotations and Alignment.
AlignmentMethod	Tracks which algorithm was successfully applied.
AlignmentResult	Container for alignment outputs.

Functions

_apply_ira_alignment(→ bool)	Performs the low-level IRA isomorphism and affine transformation.
align_structure_robust(→ AlignmentResult)	Aligns a mobile structure to a reference using IRA with an ASE fallback.
_rmsd_single(ref_atom, atom_i, config, coords_ref)	Align one image and return its RMSD (thread-safe on a copy).
calculate_rmsd_from_ref(→ numpy.ndarray)	Calculates the RMSD of each structure in a list relative to a reference.

Module Contents

rgpycrumbs.geom.api.alignment.ira_mod

class rgpycrumbs.geom.api.alignment.IRAMatchInputs

Encapsulates the raw arrays required for an IRA graph match.

Added in version 0.1.0.

ref_count: int

ref_numbers: numpy.ndarray

ref_positions: numpy.ndarray

mobile_count: int

mobile_numbers: numpy.ndarray

mobile_positions: numpy.ndarray

kmax: float

class rgpycrumbs.geom.api.alignment.IRAMatchResults

Encapsulates the transformation outputs from the IRA algorithm.

Added in version 0.1.0.

rotation: numpy.ndarray

translation: numpy.ndarray

permutation: numpy.ndarray

hausdorff_dist: float

class rgpycrumbs.geom.api.alignment.IRAConfig

Configuration parameters for the Iterative Rotations and Alignment.

Added in version 0.1.0.

enabled: bool = False

kmax: float = 1.8

class rgpycrumbs.geom.api.alignment.AlignmentMethod(*args, **kwds)

Bases: enum.Enum

Tracks which algorithm was successfully applied.

Added in version 0.1.0.

ASE_PROCRUSTES

IRA_PERMUTATION

NONE

class rgpycrumbs.geom.api.alignment.AlignmentResult

Container for alignment outputs.

Added in version 0.1.0.

Parameters:

• atoms – The aligned structure (modified in-place, but returned for chaining).

• method – The specific algorithm that was used.

atoms: ase.Atoms

method: AlignmentMethod

property used_ira: bool

Helper to maintain backward compatibility with boolean checks.

rgpycrumbs.geom.api.alignment._apply_ira_alignment(ref_atoms: ase.Atoms, mobile_atoms: ase.Atoms, config: IRAConfig) → bool

Performs the low-level IRA isomorphism and affine transformation.

This function modifies mobile_atoms in-place. It returns True if the alignment succeeds, or False if an error occurs or IRA remains unavailable.

rgpycrumbs.geom.api.alignment.align_structure_robust(ref_atoms: ase.Atoms, mobile_atoms: ase.Atoms, ira_config: IRAConfig) → AlignmentResult

Aligns a mobile structure to a reference using IRA with an ASE fallback.

Added in version 0.1.0.

This method minimizes the RMSD between the reference and mobile structures. It first attempts to solve the isomorphism problem (finding $P, R, t$) using IRA. If IRA fails or remains unavailable, it defaults to standard Procrustes superimposition (finding $R, t$) via ASE.

Parameters:

• ref_atoms – The fixed reference configuration.

• mobile_atoms – The configuration to align (modified in-place).

• ira_config – Configuration object with state of IRA and the adjacency cutoff distance for IRA graph matching.

Returns:

An AlignmentResult.

rgpycrumbs.geom.api.alignment._rmsd_single(ref_atom, atom_i, config, coords_ref)

Align one image and return its RMSD (thread-safe on a copy).

rgpycrumbs.geom.api.alignment.calculate_rmsd_from_ref(atoms_list: list[ase.Atoms], ira_instance, ref_atom: ase.Atoms, ira_kmax: float) → numpy.ndarray

Calculates the RMSD of each structure in a list relative to a reference.

Added in version 1.0.0.

The function first attempts the IRA algorithm to handle atom permutations. If IRA fails or lacks the necessary library, the code falls back to standard ASE Procrustes alignment via align_structure_robust.

Alignment of individual images is parallelized over threads; the IRA Fortran library and numpy both release the GIL.

Parameters:

• atoms_list – A list of ASE Atoms objects.

• ira_instance – An instantiated IRA object (or None).

• ref_atom – The reference Atoms object to align against.

• ira_kmax – kmax factor for IRA.

Returns:

An array of RMSD values.