.. oe:namespace:: OEChem


.. meta::
   :keywords: OEMCMolBase, MCMolBase


.. _OEChem_OEMCMolBase:

.. oe:class:: OEMCMolBase

   .. oe:api::

      class OEMCMolBase : public OEMolBase

   The :ref:`OEMCMolBase <OEChem_OEMCMolBase>` class provides the basic
   multi-conformer molecule in *OEChem*.  It is an abstract base class
   which defines the interface for multi-conformer molecule
   implementations. Coordinates can be stored in
   :ref:`OEHalfFloat <OEPlatform_OEHalfFloat>` (16-bit), ``float`` (32-bit),
   ``double`` (64-bit), or ``long double`` (>= 64-bit). The precision
   is determined by the constructor argument given to
   :ref:`OEMol <OEChem_OEMol>`, taken from the
   :oe:constns:`OEChem::OEMCMolType`
   namespace. :ref:`OEMCMolBase <OEChem_OEMCMolBase>` have an interface which
   allow access to conformers in a modal
   (:oe:meth:`OEChem::OEMCMolBase::GetActive`) or a non-modal manner
   (:oe:meth:`OEChem::OEMCMolBase::GetConfs`).

   The following methods are publicly inherited from :ref:`OEMolBase <OEChem_OEMolBase>`:

   =========================================================== =========================================================== ============================================================
   :oe:meth:`operator=<OEChem::OEMolBase::operator=>`          :oe:meth:`GetDimension<OEChem::OEMolBase::GetDimension>`    :oe:meth:`NumBonds<OEChem::OEMolBase::NumBonds>`            
   :oe:meth:`operator bool<OEChem::OEMolBase::operator bool>`  :oe:meth:`GetEnergy<OEChem::OEMolBase::GetEnergy>`          :oe:meth:`NumGroups<OEChem::OEMolBase::NumGroups>`          
   :oe:meth:`Clear<OEChem::OEMolBase::Clear>`                  :oe:meth:`GetGroup<OEChem::OEMolBase::GetGroup>`            :oe:meth:`OrderAtoms<OEChem::OEMolBase::OrderAtoms>`        
   :oe:meth:`ClearCoords<OEChem::OEMolBase::ClearCoords>`      :oe:meth:`GetGroups<OEChem::OEMolBase::GetGroups>`          :oe:meth:`OrderBonds<OEChem::OEMolBase::OrderBonds>`        
   :oe:meth:`Compress<OEChem::OEMolBase::Compress>`            :oe:meth:`GetMaxAtomIdx<OEChem::OEMolBase::GetMaxAtomIdx>`  :oe:meth:`ResetPerceived<OEChem::OEMolBase::ResetPerceived>`
   :oe:meth:`Count<OEChem::OEMolBase::Count>`                  :oe:meth:`GetMaxBondIdx<OEChem::OEMolBase::GetMaxBondIdx>`  :oe:meth:`SetCoords<OEChem::OEMolBase::SetCoords>`          
   :oe:meth:`CreateCopy<OEChem::OEMolBase::CreateCopy>`        :oe:meth:`GetTitle<OEChem::OEMolBase::GetTitle>`            :oe:meth:`SetDimension<OEChem::OEMolBase::SetDimension>`    
   :oe:meth:`DeleteAtom<OEChem::OEMolBase::DeleteAtom>`        :oe:meth:`HasPerceived<OEChem::OEMolBase::HasPerceived>`    :oe:meth:`SetEnergy<OEChem::OEMolBase::SetEnergy>`          
   :oe:meth:`DeleteBond<OEChem::OEMolBase::DeleteBond>`        :oe:meth:`IsDataType<OEChem::OEMolBase::IsDataType>`        :oe:meth:`SetPerceived<OEChem::OEMolBase::SetPerceived>`    
   :oe:meth:`DeleteGroup<OEChem::OEMolBase::DeleteGroup>`      :oe:meth:`IsDeleted<OEChem::OEMolBase::IsDeleted>`          :oe:meth:`SetRxn<OEChem::OEMolBase::SetRxn>`                
   :oe:meth:`GetAtom<OEChem::OEMolBase::GetAtom>`              :oe:meth:`IsRxn<OEChem::OEMolBase::IsRxn>`                  :oe:meth:`SetTitle<OEChem::OEMolBase::SetTitle>`            
   :oe:meth:`GetAtoms<OEChem::OEMolBase::GetAtoms>`            :oe:meth:`NewAtom<OEChem::OEMolBase::NewAtom>`              :oe:meth:`Sweep<OEChem::OEMolBase::Sweep>`                  
   :oe:meth:`GetBond<OEChem::OEMolBase::GetBond>`              :oe:meth:`NewBond<OEChem::OEMolBase::NewBond>`              :oe:meth:`UnCompress<OEChem::OEMolBase::UnCompress>`        
   :oe:meth:`GetBonds<OEChem::OEMolBase::GetBonds>`            :oe:meth:`NewGroup<OEChem::OEMolBase::NewGroup>`            
   :oe:meth:`GetCoords<OEChem::OEMolBase::GetCoords>`          :oe:meth:`NumAtoms<OEChem::OEMolBase::NumAtoms>`            
   =========================================================== =========================================================== ============================================================

   .. oe:language:: java

      The following methods are publicly inherited from :ref:`OEMolBase <OEChem_OEMolBase>` only in Java:

      ====================================================== ====================================================== =========================================================
      :oe:meth:`GetAtomList<OEChem::OEMolBase::GetAtomList>` :oe:meth:`GetBondList<OEChem::OEMolBase::GetBondList>` :oe:meth:`GetGroupList<OEChem::OEMolBase::GetGroupList>` 
      ====================================================== ====================================================== =========================================================


   The following methods are publicly inherited from :ref:`OEBase <OESystem_OEBase>`:

   ======================================================== ========================================================= =========================================================
   :oe:meth:`operator=<OESystem::OEBase::operator=>`        :oe:meth:`GetData<OESystem::OEBase::GetData>`             :oe:meth:`IsDataType<OESystem::OEBase::IsDataType>`      
   :oe:meth:`operator+=<OESystem::OEBase::operator+=>`      :oe:meth:`GetDataIter<OESystem::OEBase::GetDataIter>`     :oe:meth:`SetBaseData<OESystem::OEBase::SetBaseData>`    
   :oe:meth:`AddBaseData<OESystem::OEBase::AddBaseData>`    :oe:meth:`GetDataType<OESystem::OEBase::GetDataType>`     :oe:meth:`SetBoolData<OESystem::OEBase::SetBoolData>`    
   :oe:meth:`AddData<OESystem::OEBase::AddData>`            :oe:meth:`GetDoubleData<OESystem::OEBase::GetDoubleData>` :oe:meth:`SetData<OESystem::OEBase::SetData>`            
   :oe:meth:`Clear<OESystem::OEBase::Clear>`                :oe:meth:`GetFloatData<OESystem::OEBase::GetFloatData>`   :oe:meth:`SetDoubleData<OESystem::OEBase::SetDoubleData>`
   :oe:meth:`CreateCopy<OESystem::OEBase::CreateCopy>`      :oe:meth:`GetIntData<OESystem::OEBase::GetIntData>`       :oe:meth:`SetFloatData<OESystem::OEBase::SetFloatData>`  
   :oe:meth:`DeleteData<OESystem::OEBase::DeleteData>`      :oe:meth:`GetStringData<OESystem::OEBase::GetStringData>` :oe:meth:`SetIntData<OESystem::OEBase::SetIntData>`      
   :oe:meth:`GetBoolData<OESystem::OEBase::GetBoolData>`    :oe:meth:`HasData<OESystem::OEBase::HasData>`             :oe:meth:`SetStringData<OESystem::OEBase::SetStringData>`
   ======================================================== ========================================================= =========================================================

   .. oe:method:: operator=
      :language: c++

      .. oe:api::

         OEMCMolBase& operator=(const OEMolBase& rhs)
         OEMCMolBase& operator=(const OEConfBase& rhs)
         OEMCMolBase& operator=(const OEMCMolBase& rhs)

      Assignment operator of multi-conformer molecules via this abstract base
      class.

      Assignment operator.


   .. oe:method:: ClearBase

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

         .. oe:api::

            void ClearBase()=0

      .. oe:language:: python

         .. oe:api:: python

            ClearBase() -> None

      Clear the generic data from the :ref:`OEBase <OESystem_OEBase>` base
      class of this object. Equivalent to just calling
      :oe:meth:`OESystem::OEBase::Clear` without actually clearing away
      molecule data like atoms, bonds, and conformers.

   .. oe:method:: ClearMCMol

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

         .. oe:api::

            void ClearMCMol()=0

      .. oe:language:: python

         .. oe:api:: python

            ClearMCMol() -> None

      Clears molecule data like atoms, bonds, and conformers without
      clearing away the :ref:`OEBase <OESystem_OEBase>` generic data.

   .. oe:method:: ClearMolBase

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

         .. oe:api::

            void ClearMolBase()=0

      .. oe:language:: python

         .. oe:api:: python

            ClearMolBase() -> None

      Equivalent to calling :oe:meth:`OEChem::OEMolBase::Clear`. 


   .. oe:method:: DeleteConf

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

         .. oe:api::

            bool DeleteConf(OEConfBase *)=0

      .. oe:language:: python

         .. oe:api:: python

            DeleteConf(arg2: OEConfBase) -> bool

      Deletes the conformer which is passed in from the
      :ref:`OEMCMolBase <OEChem_OEMCMolBase>` object.

   .. oe:method:: DeleteConfs

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

         .. oe:api::

            void DeleteConfs()=0

      .. oe:language:: python

         .. oe:api:: python

            DeleteConfs() -> None

      .. warning:: 

         :oe:meth:`OEChem::OEMCMolBase::DeleteConfs` leaves the
         :ref:`OEMCMolBase <OEChem_OEMCMolBase>` object in an unstable state.
         It should be used with care and followed shortly with a call
         to :oe:meth:`OEChem::OEMCMolBase::NewConf`.

      Deletes all of the conformers from the :ref:`OEMCMolBase <OEChem_OEMCMolBase>`
      object.
      This is a very useful function for creating a new transformed
      :ref:`OEMCMolBase <OEChem_OEMCMolBase>` from an untransformed molecule.

      .. seealso::

         :oe:src:`Listing 3<SNIPPET-FilterConfs>` code example in the
         :ref:`section_oemol_conformercreation` section


   .. oe:method:: GetActive

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

         .. oe:api::

            OEConfBase* GetActive() const = 0

      .. oe:language:: python

         .. oe:api:: python

            GetActive() -> OEConfBase

      Returns the currently active conformer of the
      :ref:`OEMCMolBase <OEChem_OEMCMolBase>` object.

      .. note::

         The :oe:meth:`OEChem::OEMCMolBase::GetActive` and
         :oe:meth:`OEChem::OEMCMolBase::SetActive` methods are often
         sufficient for accessing conformations in multi-conformer molecules.

      .. seealso::

         * :oe:meth:`OEChem::OEMCMolBase::PopActive` method
         * :oe:meth:`OEChem::OEMCMolBase::PushActive` methods
         * :oe:meth:`OEChem::OEMCMolBase::SetActive` method


   .. oe:method:: GetConf

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

         .. oe:api::

            OEConfBase* GetConf(const OESystem::OEUnaryPredicate<OEChem::OEConfBase>& pred) const = 0

      .. oe:language:: python

         .. oe:api:: python

            GetConf(arg2: OEUnaryConfPred) -> OEConfBase

      Returns the first conformer in the molecule for which the predicate passed
      in returns ``true``.

   .. oe:method:: GetConfs

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

         .. oe:api::

            OESystem::OEIterBase<OEConfBase>* GetConfs() const = 0
            OESystem::OEIterBase<OEConfBase>* GetConfs(const OESystem::OEUnaryPredicate<OEChem::OEConfBase>& pred) const = 0

      .. oe:language:: python

         .. oe:api:: python

            GetConfs() -> OEConfIter
            GetConfs(arg2: OEUnaryConfPred) -> OEConfIter


      Returns an iterator over the conformers in the multi-conformer molecule.
      The return value of this function should always be assigned to an
      :ref:`OEIter <OESystem_OEIter>` object.
      The function which takes no arguments returns an iterator over all of the
      conformers. The function which takes a predicate returns an iterator which
      only contains conformers for which the predicate returns ``true``.

   .. oe:language:: java

      .. oe:method:: GetConfList

         .. oe:api:: java

            java.util.List<OEConfBase> GetConfList()

         Returns a List of conformers in order of creation.  Note that removing a conformer
         from the list will not remove it from the molecule.

   .. oe:method:: GetMaxConfIdx

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

         .. oe:api::

            unsigned int GetMaxConfIdx() const = 0

      .. oe:language:: python

         .. oe:api:: python

            GetMaxConfIdx() -> int

      For performance reasons, conformer indices are not guaranteed to be contiguous.
      :oe:meth:`OEChem::OEMCMolBase::GetMaxConfIdx` returns a lower bound for the maximum conformer index
      i.e. all indices returned by :oe:meth:`OEChem::OEConfBase::GetIdx` of the
      multi-conformer molecule will be less than this value.
      The value returned by :oe:meth:`OEChem::OEMCMolBase::GetMaxConfIdx`
      is always at least as large as :oe:meth:`OEChem::OEMCMolBase::NumConfs`.

      This method is useful for allocating temporary external data structures
      that need to be indexed by conformer index, as returned by
      :oe:meth:`OEChem::OEConfBase::GetIdx`.

   .. oe:method:: GetMCMolTitle

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

         .. oe:api::

            const char* GetMCMolTitle() const = 0

      .. oe:language:: python

         .. oe:api:: python

            GetMCMolTitle() -> str

      Return the title for the parent molecule, don't fall back to a
      conformer title like :oe:meth:`OEChem::OEConfBase::GetTitle`.


   .. oe:method:: IsDeleted

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

         .. oe:api::

            bool IsDeleted(OEConfBase *) const = 0

      .. oe:language:: python

         .. oe:api:: python

            IsDeleted(arg2: OEConfBase) -> bool

      Returns whether the passed in conformer has already been deleted. 

      .. seealso::

         * :oe:meth:`OEChem::OEMolBase::IsDeleted` methods inherited
           from the :ref:`OEMolBase <OEChem_OEMolBase>` class

   .. oe:method:: NewConf

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

         .. oe:api::

            OEConfBase* NewConf()=0
            OEConfBase* NewConf(const OEPlatform::OEHalfFloat *)=0
            OEConfBase* NewConf(const float *)=0
            OEConfBase* NewConf(const double *)=0
            OEConfBase* NewConf(const long double *)=0
            OEConfBase* NewConf(const OEMolBase *)=0
            OEConfBase* NewConf(const OEConfBase *)=0
            OEConfBase* NewConf(const OEConfBase *, const OETrans &)=0
            OEConfBase* NewConf(const OEConfBase *, std::vector<OETorsion>& t)=0

      .. oe:language:: python

         .. oe:api:: python

            NewConf() -> OEConfBase
            NewConf(arg2: OEHalfFloat) -> OEConfBase
            NewConf(arg2: OEFloatArray) -> OEConfBase
            NewConf(arg2: OEDoubleArray) -> OEConfBase
            NewConf(arg2: Union[OEGraphMol,OEMol,OEQMol]) -> OEConfBase
            NewConf(arg2: OEConfBase) -> OEConfBase
            NewConf(arg2: OEConfBase, arg3: OETrans) -> OEConfBase
            NewConf(arg2: OEConfBase, t: List[OETorsion]) -> OEConfBase


      These methods generate a new conformer that is owned by the
      current :ref:`OEMCMolBase <OEChem_OEMCMolBase>`. Each of the methods will
      return a pointer to the newly created conformer. The
      :oe:meth:`OEChem::OEMCMolBase::NewConf` methods act as virtual
      constructors of the :ref:`OEConfBase <OEChem_OEConfBase>`
      objects. :oe:meth:`OEChem::OEMCMolBase::NewConf` constructs a
      conformer with its default constructor. ``NewConf(const
      OEMolBase *)`` and ``NewConf(const OEConfBase *)`` copy
      construct a new conformer with the coordinates from the object
      passed into the function. The objects passed in must have the
      same graph as the current :ref:`OEMCMolBase <OEChem_OEMCMolBase>`.
      ``NewConf`` that takes a :ref:`OEHalfFloat <OEPlatform_OEHalfFloat>`,
      ``float``, ``double``, or ``long double`` pointer constructs a
      new conformer with the coordinates passed in as coords. The
      array must be of length
      :oe:meth:`GetMaxAtomIdx()<OEChem::OEMolBase::GetMaxAtomIdx>` ``*
      3``, and the coordinates for each atom in the new conformer
      should be the dimension values in the array starting at
      ``coords[atom->GetIdx() * 3]``.

      Passing a ``NULL`` to any of these methods will effectively do
      nothing and just return a ``NULL`` :ref:`OEConfBase <OEChem_OEConfBase>`
      pointer.

      .. warning::

         The dimension of the conformer will be set to ``0`` for the
         NewConf default constructor. The NewConf methods that create
         conformers from coordinates will set the dimension of the
         conformer to ``3``. The NewConf methods that copy construct
         will copy the dimension from the source.

   .. oe:method:: NumConfs

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

         .. oe:api::

            unsigned int NumConfs() const = 0

      .. oe:language:: python

         .. oe:api:: python

            NumConfs() -> int

      Returns the number of conformers contained in the
      :ref:`OEMCMolBase <OEChem_OEMCMolBase>` object.

   .. oe:method:: OrderConfs

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

         .. oe:api::

            bool OrderConfs(const std::vector<OEConfBase*>& vc)=0

      .. oe:language:: python

         .. oe:api:: python

            OrderConfs(arg2: OEConfVector) -> bool

      Reorders the conformers in the molecule to the order specified
      in the vector argument. If the vector contains an incomplete
      list, the remaining conformers will come at the end. This
      function call changes the order in which the conformers are
      returned by :oe:meth:`OEChem::OEMCMolBase::GetConfs`, but does
      not change the conformer indices.

   .. oe:method:: PopActive

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

         .. oe:api::

            void PopActive()=0

      .. oe:language:: python

         .. oe:api:: python

            PopActive() -> None

      The :oe:meth:`OEChem::OEMCMolBase::PopActive` method along with the
      :oe:meth:`OEChem::OEMCMolBase::PushActive` method allow to maintain
      a stack of active conformers.

      The :oe:meth:`OEChem::OEMCMolBase::PopActive` method removes the top active
      conformer from the active stack and makes the next highest conformer
      in the stack active.

      .. seealso::

         * :oe:meth:`OEChem::OEMCMolBase::GetActive` method
         * :oe:meth:`OEChem::OEMCMolBase::SetActive` method
         * :oe:meth:`OEChem::OEMCMolBase::PushActive` method

   .. oe:method:: PushActive

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

         .. oe:api::

            bool PushActive(OEConfBase *)=0

      .. oe:language:: python

         .. oe:api:: python

            PushActive(arg2: OEConfBase) -> bool

      The :oe:meth:`OEChem::OEMCMolBase::PushActive` method along with the
      :oe:meth:`OEChem::OEMCMolBase::PopActive` method allow to maintain
      a stack of active conformers.

      The :oe:meth:`OEChem::OEMCMolBase::PushActive` method makes the new conformer
      the active one and pushes the previous active conformer down the stack.

      .. seealso::

         * :oe:meth:`OEChem::OEMCMolBase::GetActive` method
         * :oe:meth:`OEChem::OEMCMolBase::SetActive` method
         * :oe:meth:`OEChem::OEMCMolBase::PopActive` method

   .. oe:method: ResetConf # ignoring because it's weird

      .. oe:api::

         bool ResetConf(OEConfBase *, const OEConfBase *)=0

   .. oe:method:: SetActive

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

         .. oe:api::

            bool SetActive(OEConfBase *)=0

      .. oe:language:: python

         .. oe:api:: python

            SetActive(arg2: OEConfBase) -> bool

      Makes the conformer passed in become the active conformer.
      The conformer passed in must already be a member of the
      :ref:`OEMCMolBase <OEChem_OEMCMolBase>` object.

      .. note::

         The :oe:meth:`OEChem::OEMCMolBase::GetActive` and
         :oe:meth:`OEChem::OEMCMolBase::SetActive` methods are often
         sufficient for accessing conformations in multi-conformer molecules.

      .. seealso::

         * :oe:meth:`OEChem::OEMCMolBase::GetActive` method
         * :oe:meth:`OEChem::OEMCMolBase::PopActive` method
         * :oe:meth:`OEChem::OEMCMolBase::PushActive` method


   .. oe:method:: SweepConfs

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

         .. oe:api::

            bool SweepConfs()=0

      .. oe:language:: python

         .. oe:api:: python

            SweepConfs() -> bool

      Cleans up unused memory and objects which may be associated with
      the conformers of the :ref:`OEMCMolBase <OEChem_OEMCMolBase>`. Renumber
      the conformer indices sequentially. This function invalidates
      the conformer indices of all conformers in a molecule. Note that
      this function doesn't guarantee that all conformer indices are
      sequential upon completion (some molecule implementations may
      treat :oe:meth:`OEChem::OEMolBase::Sweep` as a no-op).

