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

.. oe:namespace:: OEBio

.. oe:function:: OESubsetDesignUnit

   .. attention::

      |TWOLANGUAGE|

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

      .. oe:api::

         bool OESubsetDesignUnit(OEDesignUnit& du, const OEDesignUnit& refDu,
                                 const unsigned componentMask,
                                 const OESystem::OEUnaryPredicate<OEChem::OEAtomBase>& pred = OEChem::OEIsTrueAtom())

   .. oe:language:: python

      .. oe:api:: python

         OESubsetDesignUnit(du: OEDesignUnit, refDu: OEDesignUnit,
                            componentMask: int,
                            pred: OEUnaryAtomPred = OEIsTrueAtom()) -> bool

   This function generates a fully-functional
   :ref:`OEDesignUnit <OEBio_OEDesignUnit>` object (``du``) as subset of another
   OEDesignUnit (``refDu``) object. An additional bit mask
   (``componentMask``) is required to specify which components should
   be extracted as the subset. The bit mask should be specified from
   constants in the :oe:constns:`OEBio::OEDesignUnitComponents`
   namespace.
   The optional predicate can be used to subset some of the components 
   in the specified bit mask. The predicate does not have to be complete,
   e.g. two water molecules can be specified to subset the solvent category,
   but that will not subset the protein component also included in that mask.
   In essence the predicate is checked to see if it matches part of a design unit
   component and only in this case does it take effect. 

    .. warning::

       If the design unit contains a receptor it will persist in the subset, 
       except if the subset action removes a component that was part of 
       receptor generation mask, see :oe:meth:`OEBio::OEReceptor::GetTargetMask`

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

      .. oe:api::

         bool OESubsetDesignUnit(OEDesignUnit& du,
                                 const unsigned componentMask,
                                 const OESystem::OEUnaryPredicate<OEChem::OEAtomBase>& pred = OEChem::OEIsTrueAtom())
         This function behaves similarly as the above one, but does the subsetting
         on the passed design-unit removing the need for a copy.

   .. oe:language:: python

      .. oe:api:: python

         OESubsetDesignUnit(du: OEDesignUnit, componentMask: int,
                            pred: OEUnaryAtomPred = OEIsTrueAtom()) -> bool

   .. seealso::
      
      * :ref:`OEDesignUnit <OEBio_OEDesignUnit>` class
      * :ref:`OEReceptor <OEBio_OEReceptor>` class
      * :oe:constns:`OEBio::OEDesignUnitComponents` namespace
      * :oe:func:`OEBio::OEUpdateDesignUnit` function


   **Examples**

   The example below demonstrate how to use :oe:func:`OEBio::OESubsetDesignUnit`
   to subset an existing :ref:`OEDesignUnit <OEBio_OEDesignUnit>` object.

   .. oe:source:: DesignUnit.py
      :language: python
      :noindent:
      :frag:     SNIPPET-OESubsetDesignUnit

   .. oe:source:: DesignUnit.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-OESubsetDesignUnit
