PyMOL RMSD

License: PyMOL RMSD is licensed under Custom (Open-Source PyMOL Copyright Notice) and may require explicit attribution when utilized. Please refer to the license for full terms.

This toolkit is open source. Any third-party models, product names, or trademarks referenced are the property of their respective owners, and Proto is not affiliated with them.

GitHub GitHub Cite Cite Tool Source Tool Source Open as Notebook Open as Notebook Open on Proto Open on Proto

schrodinger/pymol-open-source

View repo

@misc{delano2002pymol,
  title={The {PyMOL} Molecular Graphics System},
  author={DeLano, Warren L.},
  year={2002},
  publisher={DeLano Scientific},
  address={San Carlos, CA, USA},
  url={http://www.pymol.org}
}

Copy citation

evo-design/proto-tools/proto_tools/tools/structure_alignment/pymol_rmsd

Toolkit contributors

Function	Description
`run_pymol_rmsd_alignment()`	Pairwise structure RMSD alignment using PyMOL cealign or align.	Docs Source

Background

Root mean square deviation (RMSD) measures the average distance between corresponding atoms of two structures after optimal rigid-body superposition. It is the standard summary statistic for assessing how closely a model recapitulates a reference structure, comparing alternative poses of the same complex, and quantifying conformational change between two states of the same protein. Computing a meaningful RMSD requires a residue correspondence between the two structures, which the upstream alignment routine establishes before the superposition is performed. Open-Source PyMOL exposes two distinct alignment routines that this toolkit invokes. The cealign command implements the Combinatorial Extension (CE) algorithm (Shindyalov and Bourne, 1998), which builds a structural alignment from aligned fragment pairs based on local geometry rather than a global sequence alignment. CE was developed to detect remote structural similarity below the sequence-similarity twilight zone, where the underlying sequences share too little identity for a meaningful sequence-based alignment. The align command in contrast first computes a sequence alignment using the BLOSUM62 substitution matrix, performs a structural superposition over the aligned residues, and then iterates several cycles of outlier rejection to remove residues with poor structural agreement. This routine is appropriate when the two structures share substantial sequence identity and the goal is a residue-matched superposition that excludes locally divergent regions.

Learning Resources

schrodinger/pymol-open-source (Schrödinger, LLC). The official Open-Source PyMOL repository and the source of the cealign and align commands invoked by this toolkit.
PyMOL Wiki (community-maintained). Reference documentation for the align and cealign commands and the broader PyMOL scripting interface.

Tools

PyMOL RMSD Alignment (`pymol-rmsd-alignment`)

Aligns two Structure inputs with Open-Source PyMOL and returns the post-alignment RMSD together with method-specific alignment statistics. The method configuration field selects between the CE-based cealign and the sequence-aware align routine. It also returns a superposition transform (rotation + translation) that superposes the mobile structure onto the target, so the two structures can be overlaid. Set the include_superimposed_pdb config option to also return a multi-model PDB of the overlay for download.

API Reference

Source

Input: PyMOLRMSDInput

Structure

required

Target/reference structure.

Show Structure

string

required

Raw structure content in PDB or CIF format.

string

Format of the content string (auto-detected if omitted).

BFactorType

default:"unspecified"

What the B-factor column represents.

string

Optional source identifier (filepath or tool name).

Metrics

Associated metrics (e.g., pLDDT, pTM scores, per-chain lists, pairwise matrices). None values are stripped at construction.

Structure

required

Mobile/query structure to align against the target.

Show Structure

string

required

Raw structure content in PDB or CIF format.

string

Format of the content string (auto-detected if omitted).

BFactorType

default:"unspecified"

What the B-factor column represents.

string

Optional source identifier (filepath or tool name).

Metrics

Associated metrics (e.g., pLDDT, pTM scores, per-chain lists, pairwise matrices). None values are stripped at construction.

Source

Config: PyMOLRMSDConfig

enum

default:"cealign"

PyMOL alignment routine to use.Available options: cealign, align

string

default:"target"

PyMOL selection for the target/reference structure.

string

default:"mobile"

PyMOL selection for the mobile/query structure.

number

default:"999.0"

RMSD returned when PyMOL cannot align the structures.

boolean

default:"False"

When true, also return a multi-model PDB overlaying the aligned structures (off by default to keep results small).

integer

default:"0"

Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). True is coerced to 1 and False to 0.

string

default:"cpu"

Device to run the tool on.

integer

default:"3600"

Maximum execution time in seconds. None waits indefinitely.

integer

Random seed. When set, tools run reproducibly up to small GPU float noise (see BaseToolOutput.approx_equal), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.

Source

Output: PyMOLRMSDOutput

enum

required

PyMOL alignment method used.

PyMOLRMSDMetrics

RMSD alignment metrics.

Show PyMOLRMSDMetrics

string

Name of the metric that best summarizes the result overall (e.g. "avg_plddt" for AlphaFold2). Used by downstream UI and reporting to pick a headline value.

string

Concrete Metrics subclass tag; enables typed reconstruction after a serialization round-trip.

SuperpositionTransform

Rigid-body transform that superposes the mobile structure onto the target. None if PyMOL didn’t return an object matrix.

string

Multi-model PDB overlaying the aligned structures (MODEL 1 = transformed mobile, MODEL 2 = target). Present only when config.include_superimposed_pdb is set and a transform was found.

Metrics

Metric	Type	Range	Availability
`rmsd`	float	≥ 0.0	always
`aligned_length`	int	≥ 0.0	cealign only
`aligned_atoms`	int	≥ 0.0	align only
`alignment_cycles`	int	≥ 0.0	align only
`alignment_score`	float	unbounded	align only
`pre_refinement_rmsd`	float	≥ 0.0	align only
`pre_refinement_aligned_atoms`	int	≥ 0.0	align only
`aligned_residues`	int	≥ 0.0	align only

Applications

This tool is appropriate for any analysis that needs a pairwise structural superposition of two proteins. Representative applications include scoring designed structures against a reference template, quantifying conformational drift across molecular dynamics snapshots, comparing predicted poses against experimental structures, and evaluating backbone or side-chain changes introduced by mutation.

Usage Tips

method selects the alignment routine and should match the expected sequence relationship between the two inputs. The default cealign runs the Combinatorial Extension algorithm and is appropriate for proteins with low sequence similarity. align performs a sequence alignment followed by structural superposition and iterative outlier rejection, and is more appropriate when the two inputs share substantial sequence identity.
cealign and align populate different metric fields. A cealign call returns rmsd and aligned_length (the length of the CE alignment in CA atoms, equivalent to aligned residues since cealign operates only on CA atoms). An align call returns rmsd (after refinement), aligned_atoms, alignment_cycles, alignment_score, pre_refinement_rmsd, pre_refinement_aligned_atoms, and aligned_residues. Metric fields that do not apply to the selected method are returned as None.
target_selection and mobile_selection accept arbitrary PyMOL selection strings. The defaults select the full target and mobile objects. Pass a refined selection such as "target and name CA" or "target and chain A" to restrict the alignment to a specific residue subset, chain, or atom set. Selection syntax follows the standard PyMOL grammar documented on the PyMOL Wiki.
A failed alignment returns failure_rmsd rather than raising an exception. When PyMOL cannot align the two structures (for example, when the structures are too dissimilar for CE to converge), the call returns the configured failure_rmsd value (default 999.0) and attaches the underlying error message to the result metadata as alignment_error. This sentinel-value approach lets calling code distinguish a failed alignment from a near-zero RMSD between two essentially identical structures.

Toolkit Notes

These apply to every PyMOL RMSD tool in this toolkit (pymol-rmsd-alignment).

Outputs are returned as typed metric objects. Each PyMOLRMSDMetrics result carries the post-alignment rmsd together with the method-specific metrics described under Usage Tips, and the output’s superposition field carries the rotation/translation that overlays the mobile structure onto the target (None if PyMOL returned no object matrix). The headline primary_metric is rmsd, and results can be exported to JSON through the standard export method.
Inputs accept a Structure object, a file path, or raw PDB or mmCIF content. Each input is normalised to a Structure before scoring, and the corresponding PDB text is passed to PyMOL through a temporary file.

Example notebook: See the full working example for a copy-paste-ready walkthrough.

Infrastructure Guides

The following guides cover how to run tools efficiently and at scale.

Tool Persistence

Keep a tool’s model warm across calls instead of reloading it every invocation.

Device Management

How GPUs are allocated to tools and how to target specific devices.

Parallel Execution

Fan a batch of inputs out across multiple GPUs.

Tools

Guides

Tool Catalog

Concepts

Implementing a Tool

Background

Learning Resources

Tools

PyMOL RMSD Alignment (`pymol-rmsd-alignment`)

API Reference

Applications

Usage Tips

Toolkit Notes

Infrastructure Guides

Tool Persistence

Device Management

Parallel Execution

​Background

​Learning Resources

​Tools

​PyMOL RMSD Alignment (pymol-rmsd-alignment)

​API Reference

​Applications

​Usage Tips

​Toolkit Notes

​Infrastructure Guides

Tool Persistence

Device Management

Parallel Execution

Background

Learning Resources

Tools

PyMOL RMSD Alignment (`pymol-rmsd-alignment`)

API Reference

Applications

Usage Tips

Toolkit Notes

Infrastructure Guides