iRMSD is a utility toolkit for molecular structure comparison, ensemble pruning, and symmetry-aware RMSD analysis. It combines a clean Python API with an optimized Fortran backend, providing fast and robust routines for large conformational ensembles and multiscale computational workflows.
The package offers:
- Fast RMSD evaluation including symmetry handling, canonicalization, and optimal superposition
- Structure grouping and pruning based on distance thresholds or iRMSD criteria
- Flexible Molecule class with XYZ/extXYZ parsing and ASE/RDKit interoperability
- Low- and high-level APIs that expose direct Fortran wrappers as well as convenient Python abstractions
- Extendable infrastructure for future shape metrics and ensemble workflows
iRMSD is designed for researchers working in computational chemistry, conformational sampling, machine learning for molecules, and structural bio/chem-informatics, and integrates seamlessly with tools such as ASE, RDKit, CREST/xTB, or custom multiscale simulation pipelines.
iRMSD is available via PyPI.
PyPI:
pip install irmsdPrebuilt wheels are available for Linux (manylinux) and macOS (arm64), so installation is typically straightforward. On macOS, wheel compatibility follows the version of the macos-latest runner
used by GitHub Actions.
We currently do not provide prebuilt wheels for Windows. On Windows, pip install irmsd will build the package from source. This requires: 1) Python 3.10 or newer, 2) A C/C++ compiler (e.g. Visual Studio Build Tools), 3) A Fortran compiler (e.g. Intel oneAPI Fortran, or MinGW gfortran configured for CMake). If you don’t have a Fortran toolchain available, the installation will likely fail. As an alternative, you can use WSL (Linux subsystem) and install the Linux wheels there.
For basic usage instructions, both via the CLI and in-code, see below.
Structural comparison is at the heart of conformational analysis, docking, trajectory processing, and molecular shape workflows. However, the classical Cartesian RMSD fails whenever two structures differ by atom ordering, local symmetry, or rotameric permutations. In such cases, the RMSD becomes artificially large even though the molecular properties (e.g. IR/Raman spectra, NMR shifts, energies) are identical.
The permutation invariant RMSD (iRMSD) implemented in this package solves this problem by:
- Assigning canonical atom identities independent of input atom order
- Performing symmetry-aware alignment using a divide-and-conquer approach
- Solving the linear sum assignment problem (LSAP, Hungarian algorithm) efficiently in Fortran
- Handling false enantiomers when appropriate
- Using cached memory + single precision LSAP kernel for high speed
Together, these yield a robust, fast, and scalable measure of structural similarity suitable for large ensembles (thousands of conformers), proteins, and noncovalent clusters.
Herein, the RMSD with optimal alignment and permutation is defined as:
where
- X/Y : Cartesian coordinates of the two molecules to be compared
- U: rotation matrix
- P: permutation matrix representing atom–atom assignment
- The minimization ensures best superposition and best atom correspondence
Details on the iRMSD method are extensively discussed in J. Chem. Inf. Model. 2025, 65 (9), 4501–4511 (publically accessible preprint PDF → here).
A simple application example is seen below. Here, we have two copies of the same conformer of a drug molecule. Both have entirely random atom order, and are randomly rotated, as seen in the side-by-side coordinate blocks. iRMSD is capable of aligning the structures (i.e., determine U) and restoring the correct atom order (i.e., determine P).
|
|
|
Most pentane conformers have four rotamers that differ only by permutation or inversion of terminal methyl groups. As shown in Figure 3 of the paper (page 3) :
- Conventional RMSD between these rotamers ranges from 1.2-1.8 Å
- iRMSD correctly identifies all as identical (≈ 0.0 Å) by accounting for permutations and false enantiomers
- Property calculations (IR spectra, NMR shifts) also confirm they are physically equivalent
This simple example illustrates a key problem with classical (quaternion) RMSD-based conformer comparison and the necessity of addressing both the alignment and permutation problems for chemical workflows.
A robust permutation-handling alignment algorithm must correctly classify structures as identical even if:
- randomly rotated
- atom order is randomly permuted
- (optional) mirrored ("false enantiomers")
Figures 7a–d (pages 6–7) show that iRMSD successfully returns ~0 Å for every pair in 100 randomized input coordinates of: pentane (12 atoms), TPPO (46 atoms), taxol (113 atoms), BPTI (892 atoms).
Noncovalent clusters break most RMSD algorithms because:
- the molecular graph is disconnected
- atom types are all identical (e.g., LJ75)
- graph-isomorphism methods become impossible
iRMSD handles these correctly because:
- canonical atom identity assignment does not require a connected graph and automatically falls back to the atom types
- LSAP efficiently handles the remaining permutation
For LJ75, the full 75×75 LSAP is solved successfully.
iRMSD excels in distinguishing on a single threshold parameter (RTHR):
- rotamers (same conformer → iRMSD ≈ 0 Å)
- different conformers (larger iRMSD values)
This is crucial for automated CRE pruning and is an extension to conventional (quaternion) RMSD pruning, e.g. as used in CREST.
The default RTHR threshold in irmsd to distinguish to structures as conformers is 0.125 Å, which was adapted from CREST's CREGEN procedure. Additional thresholds, e.g. for the inter-conformer energy difference (ETHR) or rotational constants (BTHR) are not required, but can be used to achieve more efficient pre-sorting.
Use iRMSD whenever you wish to:
- compare conformers with local symmetry
- prune redundant structures in CRE/CREGEN-style workflows
- merge ensembles from different levels of theory (energy-threshold independent)
- process MD trajectories where atom ordering is stable but symmetry remains
- align structures from different toolchains (RDKit ↔ xTB ↔ ORCA ↔ OpenBabel)
- classify rotamers vs conformers with physical correctness
The iRSMD package comes with an CLI tool irmsd. This tool allows you to read multiple structures (e.g. from an extended xyz-format file), an perform operations on them. There are three subcommands that can be chosen: prop, compare, and sort/prune:
usage: irmsd [-h] [-v] {prop,compare,sort,prune} ...
CLI to read an arbitrary number of structures and run selected analysis commands on them.
positional arguments:
{prop,compare,sort,prune}
Subcommand to run.
prop Compute structural properties (CN, rotational constants, canonical IDs).
compare Compare structures via iRMSD (default) or quaternion RMSD.
sort (prune) Sort, prune or cluster structures based on inter-structure measures. By
default, the more expensive iRMSD version is used. The use of the molecules'
energies (--ethr) is optional but recommended. To fall back to
the quicker, but more empirical CREGEN workflow for ensemble sorting (using
energies, quaternion RMSDs and rotational constants), use --classic
options:
-h, --help show this help message and exit
-v, --version show program's version number and exit
The prop functionality exists as an utility function and can be used to determine some atomic properties for each structure provided:
usage: irmsd prop [-h] [--cn] [--rot] [--canonical] [--heavy] structures [structures ...]
positional arguments:
structures Paths to structure files (e.g. .xyz, .pdb, .cif).
options:
-h, --help show this help message and exit
--cn Calculate coordination numbers for each structure and print them as numpy arrays.
--rot Calculate the rotational constants.
--canonical Calculate the canonical identifiers.
--heavy When calculating canonical atom identifiers, consider only heavy atoms.
The compare subcommand performs a quaternion RMSD or an iRMSD comparison of the first two structures provided. It will return the alisgned structures.
usage: irmsd compare [-h] [--quaternion] [--inversion {on,off,auto}] [--heavy] [-o OUTPUT]
[--ref-idx REF_IDX] [--align-idx ALIGN_IDX]
structures [structures ...]
positional arguments:
structures Paths to structure files (e.g. .xyz, .pdb, .cif).
options:
-h, --help show this help message and exit
--quaternion Use the quaternion-based Cartesian RMSD instead of the invariant RMSD.
--inversion {on,off,auto}
Control coordinate inversion in iRMSD runtypes: 'on', 'off', or 'auto'
(default: auto). Used only for iRMSD.
--heavy When comparing structures, consider only heavy atoms.
-o OUTPUT, --output OUTPUT
Output file name (optional). If not provided, results are only printed.
--ref-idx REF_IDX Index of the reference structure in the provided structure list (default: 0,
i.e., the first structure).
--align-idx ALIGN_IDX
Index of the structure to align to the reference structure (default: 1, i.e.,
the second structure). Used only for quaternion RMSD.
Finally, the sort (or prune) runtype performs ensemble pruning to remove redundant structures from a given structure list. It also splits the structure list into chemically distinct ensembles, should different molecules be included (currently decided via the sum formula).
usage: irmsd sort [-h] [--rthr RTHR] [--ethr [ETHR]] [--bthr BTHR] [--ewin EWIN]
[--inversion {on,off,auto}] [--align] [--classic] [--heavy] [--maxprint MAXPRINT]
[-o OUTPUT]
structures [structures ...]
positional arguments:
structures Paths to structure files (e.g. .xyz, .pdb, .cif).
options:
-h, --help show this help message and exit
--rthr RTHR Inter-structure RMSD threshold for sorting in Angström. Structures closer
than this threshold are treated as similar.
--ethr [ETHR] Inter-structure energy threshold in Hartree. If set, the default is 8.0e-5 Ha
(≈0.05 kcal/mol) or a user-specified value. Optional for iRMSD-based
runtypes.
--bthr BTHR Inter-structure rotational threshold used in the classical CREGEN sorting
procedure. The default is 0.01.
--ewin EWIN Energy window specification for CREGEN. Structures higher in energy than this
threshold (relative to the lowest energy structure in the ensemble) will be
removed. There is no default (all conformers are considered).
--inversion {on,off,auto}
Control coordinate inversion when evaluating RMSDs during sorting: 'on',
'off', or 'auto' (default: auto). Only for iRMSD-based runtypes.
--align Just sort by energy and align.
--classic, --cregen Perform conformer classification with the CREGEN workflow based on a
comparison of quaternion RMSD, energy, interatomic distances, and rotational
constants. This routine is cheaper but more empirical than iRMSD-based
sorting. Does NOT restore mismatching atom order. Does not keep individual
rotamers.
--maxprint MAXPRINT Printout option; determine how many rows are printed for each sorted ensemble.
-o OUTPUT, --output OUTPUT
Optional output file for sorted / clustered results.
For more information refer to the docs (https://pprcht.github.io/irmsd/).
A list of the provided functions and types can be found in the docs (https://pprcht.github.io/irmsd/generated/irmsd.html#module-irmsd). A simple function could look like this:
from irmsd import read_structures, sorter_irmsd_molecule, prune
# read an xyz file with multiple frames and return a list of irmsd.Molecule objects
molecules = read_structures('/PATH/TO/YOUR/input.xyz')
# Analyze the structure list and assign each molecule to a group (simple list of integers)
# as well as the aligned molecules
groups,aligned_molecules = sorter_irmsd_molecule(molecules, rthr=0.125)
# Alternatively, one can generate a pruned conformer list in-place
pruned_molecules = prune(molecules, rthr=0.125)- High-symmetry cases (e.g. C60, adamantane, etc.): Rotational axes are degenerate and an initial alignment is not possible this way.
- Interchage of atoms between molecules on different fragments in noncovalent complexes: The canonical assignment of two sub-graphs (two molecules that share no covalent connection) is currently independent. Hence, atoms (of the same element) may exchange across fragments, as for the (H2O)21 or LJ75 case.
- Mismatches in canonical atom identifiers (comparing to chemical isomers that share a sum formula but have entirely different connectivity) are currently not caught and handled automatically.
- Some quaternion RMSDs may be slightly lower when comparing entirely different conformers (e.g. see example 4, figure b): This can occur due to the imperfect alignment+LSAP since rotational axes in different conformers varying orientations. Automatically falling back to the lower quaternion RMSD is an implementation TODO.
This project is licensed under the GNU Lesser General Public License (LGPL), version 3.0 or later. You are free to use, modify, and redistribute the software under the terms of this license. See the LICENSE file for the full text.
Disclaimer:
This software is provided “as is”, without any warranty of any kind, express or implied,
including but not limited to warranties of merchantability, fitness for a particular purpose,
and noninfringement. In no event shall the authors or contributors be liable for any claim,
damages, or other liability arising from the use of this software.
© 2025 Philipp Pracht, Tobias Kaczun.
If you use this software in academic work, please acknowledge it and cite the associated publication.