pyRMSD

What is pyRMSD?

pyRMSD 4.2.1 calculates an all-versus-all root mean square deviation matrix for a matching ensemble of protein conformations. It is designed for structures that contain the same atoms in the same order, such as frames from a molecular dynamics trajectory or alternative models of one protein.

RMSD measures coordinate displacement after optimal superposition:

where $N$ is the number of selected atoms. The value is reported in Å.

How to use pyRMSD online

Run pyRMSD online by uploading or fetching at least two matching PDB conformations, selecting alpha carbons or all atoms, and choosing a QCP, Kabsch, QTRFIT, or no-superposition calculator. ProteinIQ returns every unique structure pair as a table, plus the condensed NumPy matrix and pyRMSD summary statistics.

Input requirements

Matching atom counts are necessary but not sufficient. Two unrelated structures can contain the same number of atoms while pairing the wrong coordinates. For proteins with different sequences, residue numbering, missing regions, or chain layouts, use USAlign or the RMSD calculator, which provide structure-matching workflows.

The native reader requires MODEL records. ProteinIQ preserves the captured PDB content and does not insert model boundaries or remove records. Atom correspondence and matching counts are checked by pyRMSD. Older saved jobs retain their original atom-selection defaults and PDB handling.

Atom selection

Calculator

The fitted calculators solve the same geometric objective through different numerical algorithms, so results should be very close apart from floating-point variation. OpenMP changes execution parallelism, not the scientific definition.

Results

For $n$ conformations, the table contains $n(n-1)/2$ unique pairs.

pyRMSD stores only the upper triangle because an RMSD matrix is symmetric and its diagonal is zero. pyrmsd_condensed_matrix.npy preserves that compact one-dimensional form for NumPy workflows. pyrmsd_statistics.json contains the matrix minimum, maximum, mean, standard deviation (Std. Dev.), skewness, and kurtosis. Undefined statistics, such as skewness and kurtosis for a single pair, are represented as null. pyrmsd_run.log contains the native run output and warnings.

Native API requests

Choose Native API request (JSON) to upload or paste coordinate arrays and call pyRMSD's other CPU methods. The calculator setting selects the native algorithm. Arrays contain [conformations, atoms, xyz] values in Å. JSON numbers become NumPy float64 values; an array can also be supplied as {"npy_base64": "..."} containing a float64 NumPy file. Pickled object arrays are rejected.

This example compares frames 0 and 1 and returns their superposed coordinates:

{
  "method": "pairwise",
  "reference": 0,
  "target": 1,
  "get_superposed_coordinates": true,
  "fitting_coordinates": [
    [
      [0, 0, 0],
      [1, 0, 0],
      [0, 1, 0],
      [0, 0, 1]
    ],
    [
      [0, 0, 0],
      [1.2, 0, 0],
      [0, 1, 0],
      [0, 0, 1]
    ]
  ]
}

Indices start at zero. get_superposed_coordinates is supported by pairwise and oneVsTheOthers. Supply optional calculation_coordinates to fit one atom set and measure another; its conformation count must match the fitting array. Optional fit_symmetry_groups and calc_symmetry_groups use native swap-pair groups, such as [[[0, 2], [3, 5]]]. pyRMSD applies these according to the selected method. Its matrix method does not use fitting symmetry groups. openmp_threads is a positive integer; omission retains the native default of 8. Native pairwise methods create temporary calculators internally, retaining their own native defaults.

matrixAnalysis accepts a one-dimensional condensed matrix array or its npy_base64 encoding, plus ordered queries. It loads the matrix through pyRMSD's MatrixHandler. Query methods are get and set (i, j, and value for set), get_neighbors_for_node (node, nodes, cutoff), element_neighbors_within_radius (node, radius), choose_node_with_higher_cardinality (nodes, cutoff), recalculateStatistics, get_number_of_rows, get_data, and calculateMin, calculateMax, calculateMean, calculateVariance, calculateSkewness, or calculateKurtosis. For highest cardinality, supply unique nodes in ascending order, as required by the native indexing routine. After editing entries, request recalculateStatistics before reading fresh statistics. Native node ordering and tie behavior are preserved.

API mode returns pyrmsd_native_result.json, the run log, and any matrix, statistics, or superposed-coordinate files produced by the method. Coordinate files preserve native float64 values. RMSDs appear in the results table; iterative coordinates and neighborhood answers are available in the files. Undefined native statistics are null in JSON. Two small native binding repairs make cache reset return Python None and make matrix editing write values using the matrix buffer's numeric type. RMSD and statistics algorithms are unchanged. CUDA calculators require a separate source build and are unavailable in this CPU deployment.

Interpreting an RMSD matrix

There is no universal threshold for a similar protein conformation. RMSD depends on protein size, atom selection, flexible termini, loops, domain motion, and whether fitting was enabled. A 2 Å all-atom RMSD is not equivalent to a 2 Å alpha-carbon RMSD.

The matrix is most informative as a relative map within one consistent ensemble:

• Low-RMSD blocks: Groups of conformations that may represent the same structural state.
• High values in one row: A possible outlier, transition structure, or malformed frame.
• Two or more blocks: Candidate conformational substates for clustering or representative selection.
• Broad all-atom values with tighter CA values: Similar backbones with differing side-chain conformations.

Global RMSD is sensitive to localized motion. A flexible terminus can increase the value even when the protein core is stable, and domain movement can dominate over local structural agreement. Atom selections should therefore be chosen before comparing experiments, and every matrix being compared should use the same selection and fitting method.

For a single reference-versus-model comparison with explicit residue matching, the RMSD calculator is easier to interpret. pyRMSD is the better choice for complete pairwise analysis of a topology-consistent ensemble, including conformations exported from molecular dynamics.