.. include:: ../substitutions

.. oe:namespace:: OEChem

.. meta::
   :keywords: OERMSD

.. oe:function:: OERMSD

   **Array-Based OERMSD**

   .. _api_Array_Based_RMSD:

   .. oe:language:: c++ java csharp

      .. oe:api::

         double OERMSD(const float* refcrds, const float* fitcrds,
                       unsigned int size, bool overlay = false,
                       double* rot = 0, double* trans = 0)
         double OERMSD(const double* refcrds, const double* fitcrds,
                       unsigned int size, bool overlay = false,
                       double* rot = 0, double* trans = 0)

   .. oe:language:: python

      .. oe:api:: python

         OERMSD(refcrds: OEFloatArray, fitcrds: OEFloatArray, size: int,
                overlay: bool = False, rot: OEDoubleArray = None,
                trans: OEDoubleArray = None) -> float
         OERMSD(refcrds: OEDoubleArray, fitcrds: OEDoubleArray, size: int,
                overlay: bool = False, rot: OEDoubleArray = None,
                trans: OEDoubleArray = None) -> float


   Returns the root mean squared deviation (i.e. RMSD) between two sets of
   Cartesian coordinates.  

   *refcrds, fitcrds*
      These arrays should be of length `size` ``*3``, and should contain
      the Cartesian coordinates of the two objects being assessed.

   *overlay*
     This flag indicates whether the RMSD of the two arrays in their
     current position is desired (``false``), or whether the lowest possible
     RMSD for the two arrays should be returned (``true``).  

   *rot, trans*
      If an overlay calculation is carried out, the functions can report the
      rotation and translation required to achieve the minimum RMSD.  An
      array of length ``double[9]`` should be passed to the **rot** argument
      and an array of length ``double[3]``
      should be passed as the **trans** argument.

   **Example:**

   .. oe:source:: OERMSD.py
      :language: python
      :noindent:
      :frag:     SNIPPET-OERMSD-ARRAY

   .. oe:source:: OERMSD.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-OERMSD-ARRAY

   .. oe:source:: OERMSD.java
      :language: java
      :noindent:
      :frag:     SNIPPET-OERMSD-ARRAY

   .. oe:source:: OERMSD.cs
      :language: csharp
      :noindent:
      :frag:     SNIPPET-OERMSD-ARRAY

   **Full Molecule-Based OERMSD**

   .. _api_Full_Molecule_Based_RMSD:

   .. oe:language:: c++ java csharp

      .. oe:api::

         double OERMSD(const OEMolBase& ref, const OEMolBase& fit,
                       bool automorph = true, bool heavyOnly = true,
                       bool overlay = false, double* rot = 0, double* trans = 0)
         bool OERMSD(const OEMolBase& ref, const OEMCMolBase& fit,
                     double* rmsdArray, bool automorph = true,
                     bool heavyOnly = true, bool overlay = false,
                     double* rot = 0, double* trans = 0)

   .. oe:language:: python

      .. oe:api:: python

         OERMSD(ref: Union[OEGraphMol,OEMol,OEQMol], fit: OEMol,
                rmsdArray: OEDoubleArray, automorph: bool = True,
                heavyOnly: bool = True, overlay: bool = False,
                rot: OEDoubleArray = None, trans: OEDoubleArray = None) -> bool
         OERMSD(ref: Union[OEGraphMol,OEMol,OEQMol],
                fit: Union[OEGraphMol,OEMol,OEQMol], automorph: bool = True,
                heavyOnly: bool = True, overlay: bool = False,
                rot: OEDoubleArray = None, trans: OEDoubleArray = None) -> float
         OERMSD(ref: Union[OEGraphMol,OEMol,OEQMol],
                fit: Union[OEGraphMol,OEMol,OEQMol],
                align: OESequenceAlignment, onlyCAlpha: bool = True,
                overlay: bool = False, rot: OEDoubleArray = None,
                trans: OEDoubleArray = None) -> float

   Calculates the root mean squared deviation (i.e. RMSD ) between two
   molecules.  

   *ref, fit*
      This function is overloaded for comparisons of a
      single-conformer (:oe:cls:`OEMolBase<OEChem::OEMolBase>`) reference
      molecule with either a single-conformer
      (:oe:cls:`OEMolBase<OEChem::OEMolBase>`) or a multi-conformer
      (:oe:cls:`OEMCMolBases<OEChem::OEMCMolBase>`) **fit** molecule.

   *rmsdArray*
      For the :ref:`OEMolBase <OEChem_OEMolBase>` vs :ref:`OEMolBase <OEChem_OEMolBase>`
      comparison, the RMSD is the return value.  For the
      :ref:`OEMolBase <OEChem_OEMolBase>` vs
      :oe:cls:`OEMCMolBase<OEChem::OEMCMolBase>` case, the RMSDs are
      returned in the **rmsdArray** array.  The **rmsdArray** passed to this
      function should be of length ``fit.GetMaxConfIdx()``.

   *automorph*
      This flag indicates whether automorphisms should be taken into account
      during the RMSD calculation.  Automorphisms are the symmetry related
      transformations of a molecule which can result in anomalously high
      RMSDs if not properly treated.  For instance, t-butyl-benzene has a
      three-fold automorphism around the t-butyl group and a two-fold
      automorphism around the benzene ring.  

   *heavyOnly*
      This flag indicates whether only heavy atoms should be considered  
      or hydrogen atoms should be also taken into account as well when
      assessing automorphisms.

   .. hint::
 
      It is strongly recommended that one should
      consider carefully before setting the 'automorph' flag to ``true``
      and the 'heavyOnly' flag to ``false`` due to the increased
      computational cost.

   *overlay*
     This flag indicates whether the RMSD of the molecules in their
     current position is desired (``false``), or whether the lowest possible
     RMSD for the two molecules should be returned (``true``).  

   *rot, trans* 
      If an overlay calculation is carried out, the functions can
      report the rotation and translation required to give this
      minimum RMSD.

      In case when the **fit** molecule is single-conformer 
      (:oe:cls:`OEMolBase<OEChem::OEMolBase>`),  array of length
      ``double[9]`` should be passed to the **rot** argument and an array
      of length ``double[3]`` should be passed as the **trans** argument.

      In case when the **fit** molecule is multi-conformer
      (:oe:cls:`OEMCMolBase<OEChem::OEMCMolBase>`), the array size of
      both **rot** and **trans** has to be multiplied by the length of
      ``fit.GetMaxConfIdx()``.

   .. hint::

      The arrays **rot** and **trans** described above can subsequently be
      applied to the **fit** molecule using the
      :oe:func:`OEChem::OERotate` and :oe:func:`OEChem::OETranslate`
      functions if desired. It is important that
      :oe:func:`OEChem::OERotate` and :oe:func:`OEChem::OETranslate`
      are applied in that order.

   .. note::

      A multi-conformer **fit** molecule (:oe:cls:`OEMCMolBases<OEChem::OEMCMolBase>`) 
      that is passed to the :oe:func:`OEChem::OERMSD` function can have 
      nonsequential conformation indices. This can occur, for example, if some 
      conformations of the molecule have been deleted.
      In this case, the returned **rmsdArray** array will
      contain ``-1.0`` RMSD values for invalid conformation indices. 
 
   **Example:**

   .. oe:source:: OERMSD.py
      :language: python
      :noindent:
      :frag:     SNIPPET-OERMSD-FULLMOL

   .. oe:source:: OERMSD.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-OERMSD-FULLMOL

   .. oe:source:: OERMSD.java
      :language: java
      :noindent:
      :frag:     SNIPPET-OERMSD-FULLMOL

   .. oe:source:: OERMSD.cs
      :language: csharp
      :noindent:
      :frag:     SNIPPET-OERMSD-FULLMOL


   **Partial Molecule-Based OERMSD**

   .. _api_Partial_Molecule_Based_RMSD:

   .. oe:language:: c++ java csharp

      .. oe:api::

         double OERMSD(const OEMolBase& ref, const OEMolBase& fit,
                       const OEMatchBase& match, bool overlay = false,
                       double* rot = 0, double* trans = 0)
         bool OERMSD(const OEMolBase& ref, const OEMCMolBase& fit,
                     double* rmsdArray, const OEMatchBase& match,
                     bool overlay = false, double* rot = 0, double* trans = 0)

   .. oe:language:: python

      .. oe:api:: python

         OERMSD(ref: Union[OEGraphMol,OEMol,OEQMol], fit: OEMol,
                rmsdArray: OEDoubleArray, match: OEMatchBase,
                overlay: bool = False, rot: OEDoubleArray = None,
                trans: OEDoubleArray = None) -> bool
         OERMSD(ref: Union[OEGraphMol,OEMol,OEQMol],
                fit: Union[OEGraphMol,OEMol,OEQMol], match: OEMatchBase,
                overlay: bool = False, rot: OEDoubleArray = None,
                trans: OEDoubleArray = None) -> float
         OERMSD(ref: Union[OEGraphMol,OEMol,OEQMol],
                fit: Union[OEGraphMol,OEQMol], rmsdArray: OEDoubleArray,
                match: OEMatchBase, overlay: bool = False,
                rot: OEDoubleArray = None, trans: OEDoubleArray = None) -> bool

   These functions are quite similar to the previous three.  However,
   rather than considering automorphisms and heavy atoms, these functions
   allow a user to explicitly determine which substructure of the
   two molecules should be used to determine the RMSD. 

   *ref, fit*
      This function is overloaded for comparisons of a
      single-conformer (:oe:cls:`OEMolBase<OEChem::OEMolBase>`) reference
      molecule with either a single-conformer
      (:oe:cls:`OEMolBase<OEChem::OEMolBase>`) or a multi-conformer
      (:oe:cls:`OEMCMolBases<OEChem::OEMCMolBase>`) **fit** molecule.

   *rmsdArray*
      For the :ref:`OEMolBase <OEChem_OEMolBase>` vs :ref:`OEMolBase <OEChem_OEMolBase>`
      comparison, the RMSD is the return value.  For the
      :ref:`OEMolBase <OEChem_OEMolBase>` vs
      :oe:cls:`OEMCMolBase<OEChem::OEMCMolBase>` case, the RMSDs are
      returned in the **rmsdArray** array.  The **rmsdArray** passed to this
      function should be of length ``fit.GetMaxConfIdx()``.

   *match*
      The match determines the atoms of the **fit** molecule that will be
      aligned to the atoms of the `ref` molecule.
      The match can be generated by hand, or with any of the **OEChem TK**
      matching algorithms such as :ref:`OESubSearch <OEChem_OESubSearch>` or
      :ref:`OEMCSSearch <OEChem_OEMCSSearch>`.

   *overlay*
     This flag indicates whether the RMSD of the molecules in their
     current position is desired (``false``), or whether the lowest possible
     RMSD for the two molecules should be returned (``true``).  

   *rot, trans* 
      If an overlay calculation is carried out, the functions can
      report the rotation and translation required to give this
      minimum RMSD.

      In case when the **fit** molecule is single-conformer 
      (:oe:cls:`OEMolBase<OEChem::OEMolBase>`),  array of length
      ``double[9]`` should be passed to the 'rot' argument and an array of
      length ``double[3]`` should be passed as the 'trans' argument.

      In case when the **fit** molecule is multi-conformer
      (:oe:cls:`OEMCMolBase<OEChem::OEMCMolBase>`), the array size of
      both `rot` and `trans` has to be multiplied by the length of
      ``fit.GetMaxConfIdx()``.

   .. hint::

      The arrays **rot** and **trans** described above can subsequently be
      applied to the **fit** molecule using the
      :oe:func:`OEChem::OERotate` and :oe:func:`OEChem::OETranslate`
      functions if desired. It is important that
      :oe:func:`OEChem::OERotate` and :oe:func:`OEChem::OETranslate`
      are applied in that order.

   **Example:**

   .. oe:source:: OERMSD.py
      :language: python
      :noindent:
      :frag:     SNIPPET-OERMSD-PARTMOL

   .. oe:source:: OERMSD.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-OERMSD-PARTMOL

   .. oe:source:: OERMSD.java
      :language: java
      :noindent:
      :frag:     SNIPPET-OERMSD-PARTMOL

   .. oe:source:: OERMSD.cs
      :language: csharp
      :noindent:
      :frag:     SNIPPET-OERMSD-PARTMOL
         
   .. seealso::

      * :oe:func:`OEChem::OEWeightedRMSD` function
      * :ref:`OEConfRMSD <OEChem_OEConfRMSD>` class

   .. admonition:: Code Example

      * :ref:`section_example_oechem_smartsalign` example
      * :ref:`section_example_oechem_cliquealign` example
