{"id":15018288,"url":"https://github.com/charnley/rmsd","last_synced_at":"2025-05-14T15:08:23.986Z","repository":{"id":8221343,"uuid":"9659218","full_name":"charnley/rmsd","owner":"charnley","description":"Calculate Root-mean-square deviation (RMSD) of two molecules, using rotation, in xyz or pdb format","archived":false,"fork":false,"pushed_at":"2025-01-13T16:54:09.000Z","size":582,"stargazers_count":526,"open_issues_count":2,"forks_count":120,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-04-05T22:02:35.633Z","etag":null,"topics":["alignment","assignment","atoms","kabsch","molecule","pdb","reordering","rmsd","structure","xyz"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/charnley.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-04-24T22:46:14.000Z","updated_at":"2025-04-05T17:32:53.000Z","dependencies_parsed_at":"2023-01-13T15:00:49.057Z","dependency_job_id":"a559d554-23b3-488e-af0a-64e1d72321d8","html_url":"https://github.com/charnley/rmsd","commit_stats":{"total_commits":267,"total_committers":19,"mean_commits":"14.052631578947368","dds":0.1685393258426966,"last_synced_commit":"21cc9af3870d166d42ed0dbcc54a2dad9f2c9de1"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charnley%2Frmsd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charnley%2Frmsd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charnley%2Frmsd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charnley%2Frmsd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/charnley","download_url":"https://codeload.github.com/charnley/rmsd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248646308,"owners_count":21138988,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alignment","assignment","atoms","kabsch","molecule","pdb","reordering","rmsd","structure","xyz"],"created_at":"2024-09-24T19:51:47.206Z","updated_at":"2025-04-12T23:27:51.301Z","avatar_url":"https://github.com/charnley.png","language":"Python","readme":"Calculate Root-mean-square deviation (RMSD) of Two Molecules Using Rotation\n===========================================================================\n\nThe root mean Square Deviation (RMSD) is the most common metric for measuring structural similarity between two structures. It is typically used in molecular biology, chemistry, and computational chemistry.\n\nHowever, the result can become misleadingly large unless the input data has pre-optimized translation and rotation of the molecules in question.\nThis solution will perform this optimization before calculating optimal (minimal) RMSD values.\n\nAdditionally, if the atoms in the molecules are not correctly ordered, optimal rotation is impossible to achieve.\nThis tool utilizes several ways to solve this problem.\n\nFor more details, see below and read RMSD_ and `Kabsch algorithm`_.\n\n.. contents:: Overview\n    :depth: 1\n\nInstallation\n============\n\nThe easiest is to get the program via ``pip``.\n\n.. code-block:: bash\n\n    pip install rmsd\n\nThere is only one Python file, so you can also download `calculate_rmsd.py` and put it in your bin folder.\n\n.. code-block:: bash\n\n    wget -O calculate_rmsd https://raw.githubusercontent.com/charnley/rmsd/master/rmsd/calculate_rmsd.py\n    chmod +x calculate_rmsd\n\nDetails\n=======\n\nTo calculate the structural difference between two molecules, you might initially compute the RMSD directly (**Figure 1.a**).\nHowever, this straightforward approach could give you a misleadingly large value.\nTo get the true minimal RMSD, you must adjust for translation (**Figure 1.b**) and rotation (**Figure 1.c**). This process aligns the two molecules best, ensuring the RMSD accurately reflects their structural similarity after optimal alignment.\n\n.. list-table::\n   :header-rows: 1\n\n   * - 1.a\n     - 1.b\n     - 1.c\n\n   * - |fig1.a|\n     - |fig1.b|\n     - |fig1.c|\n\n   * - RMSD = 2.8\n     - RMSD = 0.8\n     - RMSD = 0.2\n\nAtom reordering methods are used when the atoms in two molecules are not in the same order (**Figure 2.a**).\nWhile brute-force through all possible atom combinations and calculating the optimal rotation for each is possible, this approach is computationally infeasible for large structures, as it scales $O(N!)$.\nInstead, the implemented algorithms efficiently find the optimal mapping of atoms between the two structures using smarter techniques.\n\nEach method has limitations because finding the best atom mapping depends on properly aligning structures.\nThis is usually done by comparing atom-pair distances. If the molecules are aligned, using the Hungarian_ cost minimization for atom distance works well.\nIf not, you can align the Inertia_ eigenvectors (**Figure 2.b**) as an approximation to align the molecules.\nOr, use atomic descriptors (**Figure 2.c**), independent of the coordinate system, to reorder the atoms. Note that all reordering methods have limitations and drawbacks, and the actual order might not be found.\n\n.. list-table::\n   :header-rows: 1\n\n   * - 2.a\n     - 2.b\n     - 2.c\n\n   * - |fig2.a|\n     - |fig2.b|\n     - |fig2.c|\n\nUsage examples\n==============\n\nUse ``calculate_rmsd --help`` to see all the features. Usage is pretty straight\nforward, call ``calculate_rmsd`` with two structures in either ``.xyz`` or\n``.pdb``. In this example, Ethane has the same structure but is\ntranslated in space, so the RMSD should be zero.\n\n.. code-block:: bash\n\n    calculate_rmsd tests/ethane.xyz tests/ethane_translate.xyz\n\nIt is also possible to ignore all hydrogens (useful for larger molecules where\nhydrogens move around indistinguishable) and print the rotated structure for\nvisual comparison. The output will be in XYZ format.\n\n.. code-block:: bash\n\n    calculate_rmsd --no-hydrogen --print tests/ethane.xyz tests/ethane_mini.xyz\n\nIf the atoms are scrambled and not aligned, you can use the ``--reorder``\nargument, which will align the atoms from structure B onto A.\n\nUse ``--reorder-method`` to select the reordering method.\nChoose between\nInertia_ aligned Hungarian_ distance ``inertia-hungarian`` (default),\nHungarian_ distance ``hungarian`` (if the structure is already aligned),\nsorted distance ``distance``,\natomic representation ``qml``,\nand brute force ``brute`` (for reference, don't use this).\nMore details on which to use in ``--help``.\n\n.. code-block:: bash\n\n    calculate_rmsd --reorder tests/water_16.xyz tests/water_16_idx.xyz\n\nIf you want to run multiple calculations simultaneously, it's best not to rely solely on the script.\nInstead, you can use GNU Parallel to handle this efficiently. For example, compare all ``ethane_*`` molecules using two cores and print one file and the RMSD per line.\nBash is good for stuff like that.\n\n.. code-block:: bash\n\n    find tests/resources -name \"ethane_*xyz\" | parallel -j2 \"echo -n '{} ' \u0026\u0026 calculate_rmsd --reorder --no-hydrogen tests/resources/ethane.xyz {}\"\n\nIt is also possible to use RMSD as a library in other scripts; see ``tests/*`` for example usage.\n\nKnown problems\n==============\n\nFound a bug? Submit issues or pull requests on GitHub.\n\n**Note on PDB format.** Protein Data Bank format (PDB) is column-based; however, countless examples of non-standard ``.pdb`` files exist.\nWe try to read them, but if you have trouble reading the file, check if the file format is compliant with PDB.\nFor example, some hydrogens are noted as ``HG11``, which we assume is not mercury.\n\n- https://www.wwpdb.org/documentation/file-format-content/format33/sect9.html#ATOM\n\nCitation\n========\n\nPlease cite this project when using it for scientific publications. And cite the relevant methods implemented.\n\n**Implementation**:\nCalculate Root-mean-square deviation (RMSD) of Two Molecules Using Rotation, GitHub,\nhttp://github.com/charnley/rmsd, \u003cgit commit hash or version number\u003e\n\n\n.. list-table::\n   :header-rows: 1\n\n   * - Method\n     - Argument\n     - Citation\n\n   * - **Kabsch**\n     - ``--rotation-method kabsch`` (Default)\n     - Wolfgang Kabsch (1976),\n       Acta Crystallographica, A32:922-923\n\n       http://dx.doi.org/10.1107/S0567739476001873\n\n   * - **Quaternion**\n     - ``--rotation-method quaternion``\n     - Walker, Shao \u0026 Volz (1991),\n       CVGIP: Image Understanding, 54:358-367,\n\n       http://dx.doi.org/10.1016/1049-9660(91)90036-o\n\n   * - **Distance Hungarian Assignment**\n     - ``--reorder-method inertia-hungarian`` (Default)\n     - Crouse (2016). Vol. 52, Issue 4, pp. 1679–1696, IEEE.\n\n       http://dx.doi.org/10.1109/TAES.2016.140952\n\n   * - **FCHL19**\n     - ``--reorder-method qml``\n     - Christensen et al (2020), J. Chem. Phys. 152, 044107\n\n       https://doi.org/10.1063/1.5126701\n\nReferences\n==========\n\n- https://en.wikipedia.org/wiki/Root-mean-square_deviation\n- https://en.wikipedia.org/wiki/Kabsch_algorithm\n- https://en.wikipedia.org/wiki/Hungarian_algorithm\n- https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.linear_sum_assignment.html\n\n.. _RMSD: https://en.wikipedia.org/wiki/Root-mean-square_deviation\n.. _Kabsch algorithm: https://en.wikipedia.org/wiki/Kabsch_algorithm\n.. _Hungarian: https://en.wikipedia.org/wiki/Hungarian_algorithm\n.. _Inertia: https://en.wikipedia.org/wiki/Moment_of_inertia\n\n\n.. |fig1.a| image:: https://raw.githubusercontent.com/charnley/rmsd/master/docs/figures/fig_rmsd_nothing.png\n.. |fig1.b| image:: https://raw.githubusercontent.com/charnley/rmsd/master/docs/figures/fig_rmsd_recentered.png\n.. |fig1.c| image:: https://raw.githubusercontent.com/charnley/rmsd/master/docs/figures/fig_rmsd_rotated.png\n\n.. |fig2.a| image:: https://raw.githubusercontent.com/charnley/rmsd/master/docs/figures/fig_reorder_problem.png\n.. |fig2.b| image:: https://raw.githubusercontent.com/charnley/rmsd/master/docs/figures/fig_reorder_inertia.png\n.. |fig2.c| image:: https://raw.githubusercontent.com/charnley/rmsd/master/docs/figures/fig_reorder_qml.png\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharnley%2Frmsd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcharnley%2Frmsd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharnley%2Frmsd/lists"}