.. oe:namespace:: OEFastROCS

.. meta::
   :keywords: OEPrepareFastROCSMol

.. oe:function:: OEPrepareFastROCSMol

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

      .. oe:api::

         bool OEPrepareFastROCSMol(OEChem::OEMCMolBase& mol)
         bool OEPrepareFastROCSMol(OEChem::OEMCMolBase& mol,
                                   const OEShape::OEColorForceField& cff)

   .. oe:language:: python

      .. oe:api:: python

         OEPrepareFastROCSMol(mol: OEMol, cff: OEColorForceField) -> bool
         OEPrepareFastROCSMol(mol: OEMol) -> bool

   Prepares the molecule ``mol`` to improve the performance of loading
   the molecule into memory as an :ref:`OEShapeDatabase <OEFastROCS_OEShapeDatabase>`
   object from an :oe:const:`OEChem::OEFormat::OEB` file. The following
   steps are taken to improve the performance of
   :oe:meth:`OEFastROCS::OEShapeDatabase::Open` by as much as 10-fold:

   - Sets the energy of each conformer to ``0.0`` to avoid writing it
     to OEB.
   - Suppresses hydrogens and reorders reference conformers for
     compression.
   - Pre-calculates color atoms.
   - Pre-calculates self-color and self-shape terms for all conformers.

   It is recommended to call :oe:func:`OEChem::OEPRECompress` on
   the :ref:`oemolostream <OEChem_oemolostream>` before writing out to
   ``OEB``. This will store conformers in "PRE-compressed" form
   therefore alleviating the need to Gzip the ``OEB`` file and
   consequently improving the performance of
   :oe:meth:`OEChem::OEMolDatabase::Open`.
   In general, calling :oe:func:`OEFastROCS::OEPrepareFastROCSMol` and
   :oe:func:`OEChem::OEPRECompress` will result in a smaller ``OEB``
   file than the default ``OEB.GZ`` output from OMEGA.

   Additionally, if ``OEB`` file size is of chief concern a further reduction in
   file size can be achieved by using an
   :oe:const:`OEChem::OEMCMolType::HalfFloatCartesian` molecule, which
   stores reference coordinates and torsions in half floating
   point precision (16-bit). The following code snippet demonstrates
   how to cast the resultant molecule from :oe:func:`OEFastROCS::OEPrepareFastROCSMol`
   to use half precision:

   .. code-block:: c++

      OEPrepareFastROCSMol(mol);
      OEMol halfMol(mol, OEMCMolType::HalfFloatCartesian);
      OEWriteMolecule(ofs, halfMol);

   .. code-block:: python

      OEPrepareFastROCSMol(mol)
      halfMol = OEMol(mol, OEMCMolType_HalfFloatCartesian)
      OEWriteMolecule(ofs, halfMol)

   16-bit floating point will give a file size saving of approximately
   12% with a tradeoff of about 7% more performance when
   loading the OEB from disk into memory.

   .. note::

      By default, :oe:func:`OEFastROCS::OEPrepareFastROCSMol` will
      cache color atoms and self color terms for the
      :oe:const:`OEShape::OEColorFFType::ImplicitMillsDean` color
      force field. The second overload that takes a
      :ref:`OEColorForceField <OEShape_OEColorForceField>` can be used to override
      this default.

