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

.. oe:namespace:: OESpruce

..  _OESpruce_OEMakeDesignUnits:

.. oe:function:: OEMakeDesignUnits

   .. attention::

      |TWOLANGUAGE|

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

      .. oe:api::

         OESystem::OEIterBase<OEBio::OEDesignUnit>* OEMakeDesignUnits(const OEChem::OEMolBase& structure,
                                                                      const OESpruce::OEStructureMetadata& metadata = OESpruce::OEStructureMetadata(),
                                                                      const OESpruce::OEMakeDesignUnitOptions& opts = OESpruce::OEMakeDesignUnitOptions(),
                                                                      const std::string siteResidue = "")
         OESystem::OEIterBase<OEBio::OEDesignUnit>* OEMakeDesignUnits(const OEChem::OEMolBase& structure,
                                                                      const OESystem::OESkewGrid& electronDensity,
                                                                      const OESpruce::OEStructureMetadata& metadata = OESpruce::OEStructureMetadata(),
                                                                      const OESpruce::OEMakeDesignUnitOptions& opts = OESpruce::OEMakeDesignUnitOptions(),
                                                                      const std::string siteResidue = "")
         OESystem::OEIterBase<OEBio::OEDesignUnit>* OEMakeDesignUnits(const OEChem::OEMolBase& structure,
                                                                      const OEBio::OEDesignUnit& designUnitReference,
                                                                      const OESpruce::OEStructureMetadata& metadata = OESpruce::OEStructureMetadata(),
                                                                      const OESpruce::OEMakeDesignUnitOptions& opts = OESpruce::OEMakeDesignUnitOptions(),
                                                                      const std::string siteResidue = "")
         OESystem::OEIterBase<OEBio::OEDesignUnit>* OEMakeDesignUnits(const OEChem::OEMolBase& structure,
                                                                      const OESystem::OESkewGrid& electronDensity,
                                                                      const OEBio::OEDesignUnit& designUnitReference,
                                                                      const OESpruce::OEStructureMetadata& metadata = OESpruce::OEStructureMetadata(),
                                                                      const OESpruce::OEMakeDesignUnitOptions& opts = OESpruce::OEMakeDesignUnitOptions(),
                                                                      const std::string siteResidue = "")

   .. oe:language:: python

      .. oe:api:: python

         OEMakeDesignUnits(structure: Union[OEGraphMol,OEMol,OEQMol],
                           metadata: OEStructureMetadata = OEStructureMetadata(),
                           opts: OEMakeDesignUnitOptions = OEMakeDesignUnitOptions(),
                           siteResidue: str = "") -> Iterable[OEDesignUnit]
         OEMakeDesignUnits(structure: Union[OEGraphMol,OEMol,OEQMol],
                           designUnitReference: OEDesignUnit,
                           metadata: OEStructureMetadata = OEStructureMetadata(),
                           opts: OEMakeDesignUnitOptions = OEMakeDesignUnitOptions(),
                           siteResidue: str = "") -> Iterable[OEDesignUnit]

   Return an iterator over all :ref:`OEDesignUnit <OEBio_OEDesignUnit>` objects
   that can be produced from the input :ref:`OEMolBase <OEChem_OEMolBase>`
   structure. A reference structure to be used for biounit extraction
   and structural superposition can be passed in through the
   `designUnitReference` argument, while information regarding the
   experimental data as well as basic options for constructing the
   design units themselves can be provided through the
   :ref:`OEStructureMetadata <OESpruce_OEStructureMetadata>` (`metadata`), :ref:`OESkewGrid <OESystem_OESkewGrid>` (`electronDensity`) and
   :ref:`OEMakeDesignUnitOptions <OESpruce_OEMakeDesignUnitOptions>` (`opts`) arguments,
   respectively. The input option of providing a electron density map can be used to calculate Iridium score. For more information about the Iridium score, see :ref:`Iridium chapter of that toolkit <chapter_sprucetk_iridium>`. The :ref:`OEStructureMetadata <OESpruce_OEStructureMetadata>` class stores constants for use with OEFieldMeta. These attributes (e.g. symmetry) are used to construct DUs. There is an input option to specify a binding site using a single residue specification
   if apo (or holo). The format is "name:num:insert code:chainid", e.g. "ASP:25: :A" indicating Aspartic
   acid 25 in chain A. Note: A blank/whitespace character is used for the insert code, which is a typical use case.

   .. note::

      This function will return an iterator over
      :ref:`OEDesignUnit <OEBio_OEDesignUnit>` pointers, where the system's
      molecules have been binned into categories given by the
      :oe:constns:`OEBio::OEDesignUnitComponents` namespace. Although
      an :oe:constns:`OEBio::OEDesignUnitComponents::Metals` category exists, depending
      on the proximity of the metal to the design unit's binding site, the metal may be contained in either the
      :oe:constns:`OEBio::OEDesignUnitComponents::Cofactors` category if it falls within
      a cutoff to the binding site, or in the
      :oe:constns:`OEBio::OEDesignUnitComponents::Metals` category if not.

   .. admonition:: Code Example

      * :ref:`spruce_examples_make_design_units` example

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

.. seealso::

  * :ref:`OEMakeDesignUnitOptions <OESpruce_OEMakeDesignUnitOptions>` class
