.. # split by hand

.. include:: ../substitutions

.. oe:namespace:: OEBio

.. meta::
   :keywords: OEGetMolComplexFragments

.. oe:function:: OEGetMolComplexFragments

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

      .. oe:api::

         bool OEGetMolComplexFragments(std::vector<OEChem::OEAtomBondSet>& frags,
                                       const OEChem::OEMolBase& mol,
                                       const OESplitMolComplexOptions& opt = OESplitMolComplexOptions())

   .. oe:language:: python

      .. oe:api:: python

         OEGetMolComplexFragments(frags: OEAtomBondSetVector,
                                  mol: Union[OEGraphMol,OEMol,OEQMol],
                                  opt: OESplitMolComplexOptions = OESplitMolComplexOptions()) -> bool

   Analyze the input ``mol`` and generate
   a vector of :oe:cls:`OEAtomBondSets<OEChem::OEAtomBondSet>` that describe
   each connected fragment according to its functional role.
   The ``frags`` vector can be used to
   :oe:func:`count<OEBio::OECountMolComplexSites>` binding sites,
   :oe:func:`combine<OEBio::OECombineMolComplexFragments>` fragments
   into a molecule, or :oe:func:`filter<OEBio::OEFilterMolComplexFragments>`
   fragments by role.

   Using an :oe:cls:`OEAtomBondSet<OEChem::OEAtomBondSet>` vector and then
   filtering several times to produce molecules can be much more efficient
   compared to using the :oe:func:`OEBio::OESplitMolComplex` or
   :oe:func:`OEBio::OEGetMolComplexComponents` functions.

   .. oe:language:: python

      To create an :oe:cls:`OEAtomBondSet<OEChem::OEAtomBondSet>` vector:

      .. code-block:: python

         frags = OEAtomBondSetVector()

   .. oe:language:: java

      To create an :oe:cls:`OEAtomBondSet<OEChem::OEAtomBondSet>` vector:

      .. code-block:: java

         OEAtomBondSetVector frags = new OEAtomBondSetVector();

   .. oe:language:: csharp

      To create an :oe:cls:`OEAtomBondSet<OEChem::OEAtomBondSet>` vector:

      .. code-block:: csharp

         OEAtomBondSetVector frags = new OEAtomBondSetVector();


   The process is controlled by
   an optional :ref:`OESplitMolComplexOptions <OEBio_OESplitMolComplexOptions>` object.

   Returns ``false`` if the task could not be performed
   (for example, if ``mol`` is empty).

   .. warning::

      The input molecule should contain *PDB*
      :ref:`residue information<section_biopolymer_residues>`
      such as residue name, which is used during the
      classification process, either from a PDB format file or
      through :oe:func:`residue perception<OEChem::OEPerceiveResidues>`.
      Molecular complexes read from files in formats that lack this
      information (for example *SDF*) may be split inappropriately unless
      residues are perceived after input.

   .. seealso::

      * :ref:`section_split_mol_complex` section
      * :ref:`OEAtomBondSet <OEChem_OEAtomBondSet>` class
      * :ref:`OESplitMolComplexOptions <OEBio_OESplitMolComplexOptions>` class
      * :oe:func:`OEBio::OECombineMolComplexFragments` function
      * :oe:func:`OEBio::OEFilterMolComplexFragments` function
      * :oe:func:`OEBio::OECountMolComplexSites` function
      * :oe:func:`OEBio::OESplitMolComplex` function
