1
2.. image:: https://travis-ci.org/charnley/rmsd.svg?branch=master
3    :target: https://travis-ci.org/charnley/rmsd
4
5
6.. image:: https://badge.fury.io/py/rmsd.svg
7    :target: https://badge.fury.io/py/rmsd
8
9
10Calculate Root-mean-square deviation (RMSD) of Two Molecules Using Rotation
11===========================================================================
12
13The root-mean-square deviation (RMSD) is calculated, using Kabsch algorithm
14(1976) or Quaternion algorithm (1991) for rotation, between two Cartesian
15coordinates in either ``.xyz`` or ``.pdb`` format, resulting in the minimal
16RMSD.
17
18For more information please read RMSD_ and `Kabsch algorithm`_.
19
20.. _RMSD: http://en.wikipedia.org/wiki/Root-mean-square_deviation
21.. _Kabsch algorithm: http://en.wikipedia.org/wiki/Kabsch_algorithm
22
23Motivation
24----------
25
26You have molecule A and B and want to calculate the structural difference
27between those two. If you just calculate the RMSD_ straight-forward you might
28get a too big of a value as seen below. You would need to first recenter the
29two molecules and then rotate them unto each other to get the true minimal
30RMSD. This is what this script does.
31
32==========  ===========  ==========
33No Changes  Re-centered  Rotated
34----------  -----------  ----------
35|begin|     |translate|  |rotate|
36==========  ===========  ==========
37RMSD 2.50   RMSD 1.07    RMSD 0.25
38==========  ===========  ==========
39
40.. |begin| image:: https://raw.githubusercontent.com/charnley/rmsd/master/img/plot_beginning.png
41.. |translate| image:: https://raw.githubusercontent.com/charnley/rmsd/master/img/plot_translated.png
42.. |rotate| image:: https://raw.githubusercontent.com/charnley/rmsd/master/img/plot_rotated.png
43
44
45Citation
46--------
47
48- **Implementation**:
49    Calculate Root-mean-square deviation (RMSD) of Two Molecules Using Rotation, GitHub,
50    http://github.com/charnley/rmsd, <git commit hash or version number>
51
52- **Kabsch algorithm**:
53    Kabsch W., 1976,
54    A solution for the best rotation to relate two sets of vectors,
55    Acta Crystallographica, A32:922-923,
56    doi: http://dx.doi.org/10.1107/S0567739476001873
57
58- **Quaternion algorithm**:
59    Michael W. Walker and Lejun Shao and Richard A. Volz, 1991,
60    Estimating 3-D location parameters using dual number quaternions, CVGIP: Image Understanding, 54:358-367,
61    doi: http://dx.doi.org/10.1016/1049-9660(91)90036-o
62
63Please cite this project when using it for scientific publications.
64
65
66Installation
67------------
68
69Easiest is to get the program vis PyPi under the package name ``rmsd``,
70
71.. code-block:: bash
72
73    pip install rmsd
74
75
76or download the project from GitHub via
77
78.. code-block:: bash
79
80    git clone https://github.com/charnley/rmsd
81
82
83There is only one Python file, so you can also download `calculate_rmsd.py` and
84put it in your bin folder.
85
86.. code-block:: bash
87
88    wget -O calculate_rmsd https://raw.githubusercontent.com/charnley/rmsd/master/rmsd/calculate_rmsd.py
89    chmod +x calculate_rmsd
90
91Usage examples
92--------------
93
94Use ``calculate_rmsd --help`` to see all the features. Usage is pretty straight
95forward, call ``calculate_rmsd`` with two structures in either ``.xyz`` or
96``.pdb``. In this example Ethane has the exact same structure, but is
97translated in space, so the RMSD should be zero.
98
99.. code-block:: bash
100
101    calculate_rmsd tests/ethane.xyz tests/ethane_translate.xyz
102
103It is also possible to ignore all hydrogens (useful for larger molecules where
104hydrogens move around indistinguishable) and print the rotated structure for
105visual comparison. The output will be in XYZ format.
106
107.. code-block:: bash
108
109    calculate_rmsd --no-hydrogen --print tests/ethane.xyz tests/ethane_mini.xyz
110
111If the atoms are scrambled and not aligned you can use the ``--reorder``
112argument which will align the atoms from structure B unto A. Use
113``--reorder-method`` to select what method for reordering. Choose between
114Hungarian_ (default), distance (very approximate) and brute force (slow).
115
116.. _Hungarian: https://en.wikipedia.org/wiki/Hungarian_algorithm
117
118.. code-block:: bash
119
120    calculate_rmsd --reorder tests/water_16.xyz tests/water_16_idx.xyz
121
122
123It is also possible to use RMSD as a library in other scripts, see `example.py` for example usage.
124
125
126Problems?
127---------
128
129Submit issues or pull requests on GitHub.
130
131
132Contributions
133-------------
134
135Please note that we are using ``black`` with line length of 79. Easiest way to
136abide to the code standard is to install the following packages.
137
138.. code-block:: bash
139
140    pip install black flake8 autoflake isort pytest
141
142and
143
144.. code-block:: bash
145
146    make format test lint
147
148to auto-format and test the code.
149
150
151