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

.. oe:namespace:: OESpruce

..  _OESpruce_OESplitBioUnitToComponents:

.. oe:function:: OESplitBioUnitToComponents

   .. attention::

      |TWOLANGUAGE|

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

      .. oe:api::

         bool OESplitBioUnitToComponents(OEBio::OEDesignUnit& du,
                                         const OEChem::OEMolBase& bioUnit,
                                         OEChem::OEMolBase& packingMol,
                                         const OESpruce::OEDesignUnitSplitOptions& opts)

   .. oe:language:: python

      .. oe:api:: python

         OESplitBioUnitToComponents(du: OEDesignUnit,
                                    bioUnit: Union[OEGraphMol,OEMol,OEQMol],
                                    packingMol: Union[OEGraphMol,OEMol,OEQMol],
                                    opts: OEDesignUnitSplitOptions) -> bool

   Splits the biological unit molecule ``bioUnit`` into the component categories
   of a :ref:`OEDesignUnit <OEBio_OEDesignUnit>` (protein, ligand, solvent, metals,
   etc.) using the splitting criteria defined in
   :ref:`OEDesignUnitSplitOptions <OESpruce_OEDesignUnitSplitOptions>` ``opts``.
   The resulting components are stored in ``du``, and any packing residues are
   placed in ``packingMol``. Returns ``true`` on success.

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

      .. oe:api::

         bool OESplitBioUnitToComponents(OEBio::OEDesignUnit& du,
                                         const OEChem::OEMolBase& bioUnit,
                                         OEChem::OEMolBase& packingMol,
                                         const OESpruce::OEDesignUnitSplitOptions& opts,
                                         const std::vector<std::string>& ligandNames)

   .. oe:language:: python

      .. oe:api:: python

         OESplitBioUnitToComponents(du: OEDesignUnit,
                                    bioUnit: Union[OEGraphMol,OEMol,OEQMol],
                                    packingMol: Union[OEGraphMol,OEMol,OEQMol],
                                    opts: OEDesignUnitSplitOptions,
                                    ligandNames: OEStringVector) -> bool

   As the first overload, but restricts ligand detection to residues whose
   three-letter codes appear in ``ligandNames``. This allows explicit control
   over which heterogens are classified as ligands rather than cofactors or
   excipients.

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

      .. oe:api::

         bool OESplitBioUnitToComponents(OEBio::OEDesignUnit& du,
                                         const OEChem::OEMolBase& bioUnit,
                                         OEChem::OEMolBase& packingMol,
                                         const OESpruce::OEDesignUnitSplitOptions& opts,
                                         const std::map<unsigned, std::vector<std::string>>& componentNames)

   .. oe:language:: python

      .. oe:api:: python

         OESplitBioUnitToComponents(du: OEDesignUnit,
                                    bioUnit: Union[OEGraphMol,OEMol,OEQMol],
                                    packingMol: Union[OEGraphMol,OEMol,OEQMol],
                                    opts: OEDesignUnitSplitOptions) -> bool
         OESplitBioUnitToComponents(du: OEDesignUnit,
                                    bioUnit: Union[OEGraphMol,OEMol,OEQMol],
                                    packingMol: Union[OEGraphMol,OEMol,OEQMol],
                                    opts: OEDesignUnitSplitOptions,
                                    ligandNames: OEStringVector) -> bool

   As the first overload, but accepts a map of
   :oe:constns:`OEBio::OEDesignUnitComponents` component IDs to lists of
   three-letter residue codes, giving fine-grained control over which residues
   are assigned to each component category.

   The input ``bioUnit`` must have 3D coordinates assigned.

   .. seealso::

      * :ref:`OEDesignUnitSplitOptions <OESpruce_OEDesignUnitSplitOptions>` class
      * :oe:func:`OESpruce::OEMakeDesignUnits` function
      * :oe:func:`OESpruce::OEMakeBioDesignUnits` function
      * :oe:constns:`OEBio::OEDesignUnitComponents` namespace
