.. include:: ../../toolkit-substitutions

.. oe:namespace:: OEChem

.. meta::
   :keywords: OEApplyStateFromRef

.. oe:function:: OEApplyStateFromRef

   .. attention::

      |PRELIMINARY-API|

   This function can be used to change the tautomer state or a fix a broken valence state in a 3D
   molecule, based on a reference state (not required to be 3D). The function matches the substructures
   and transfers the state of the reference, like bond-orders, formal charge assignments, and hydrogen assignments
   to the input molecule.
   The input molecule can be smaller than the reference
   molecule, as this is intended to work for small molecule crystal structures where part of the molecule can have
   been degraded in the experiment. It also works for molecules that have been covalently bound to a protein,
   such that there is an R-group in place of the broken covalent bond.
   Due to symmetries in the substructure graph match, that are not unique in 3D, the function returns an iterator of output
   molecules where the state of the reference has been applied. An simple example would be a 3D molecule with two carboxylic
   acid groups on either side of a beneze ring. If the state being applied has one neutral carboxylic acid, and one negatively
   charged, two output molecules would have to be generated. While they are symmetric, if the 3D molecule is bound
   in a protein pocket, the two groups are not identical and one very likely fits the local environment better than
   the other, which will need to be checked.

   .. note::

      The state of hydrogens being implicit or explicit in the output will match that of the
      state of the reference molecle. 
      
   .. note::
      
      The function currently ignores chirality of the two molecules, since this cannot be changed
      in a 3D molecule without conformational changes. However, the function will attempt to transfer chiral information on atoms 
      and bonds from the reference state by setting  the :oe:meth:`OEChem::OEAtomBase::SetChiral` flag to match 
      the :oe:meth:`OEChem::OEAtomBase::HasStereoSpecified` flag from the reference state. The user is expected to call
      :ref:`OE3DToAtomStereo <OEChem_OE3DToAtomStereo>` to convert the chiral flag to atoms with specified stereo on 3D molecules.

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

      .. oe:api::

         OESystem::OEIterBase<OEMolBase>* OEApplyStateFromRef(const OEMolBase& input,
                                                              const OEMolBase& refMol)
         OESystem::OEIterBase<OEMolBase>* OEApplyStateFromRef(const OEMolBase& input,
                                                              const std::string& refSmiles)

   .. oe:language:: python

      .. oe:api:: python

         OEApplyStateFromRef(inputState: Union[OEGraphMol,OEMol,OEQMol],
                             refState: Union[OEGraphMol,OEMol,OEQMol]) -> Iterable[Union[OEGraphMol, OEMol, OEQMol]]

  The SMILES version uses :oe:func:`OEChem::OEMolToSmiles` to convert the incoming smiles to a molecule usable for
  the substructure search.

   .. seealso::

      * :oe:func:`OEChem::OEMolToSmiles` function
      * :ref:`OESubSearch <OEChem_OESubSearch>` function
