.. _chapter_omegagpuomega:

.. _omega_part_gpuomega:

********************************************************************************
GPU-Omega
********************************************************************************

**GPU-Omega** refers to the CUDA-enabled GPU implementation of **Omega TK**. **GPU-Omega** takes
advantage of a GPU during torsion driving for accelerated conformer generation. To
make use of **GPU-Omega** conformer generation, please follow the guidelines below.

.. attention::

   **GPU-Omega** is not available in the C# version of the toolkit.

.. include:: ../../common/gpu_prereq.rst

.. _section_gpuomega_usage:

Usage
=====

* **GPU-Omega** accelerates the torsion driving component of conformer generation in **Omega TK** and is
  available through the :ref:`OEOmega <OEConfGen_OEOmega>` and :ref:`OETorDriver <OEConfGen_OETorDriver>` classes.

* For all torsion driving sampling modes except ``dense`` modes,
  if a GPU is detected at runtime, torsion driving will be carried
  out on the GPU by default. To turn this feature off, use
  :oe:meth:`OEConfGen::OETorDriveOptions::SetUseGPU`.

* The following code shows how to turn off **GPU-Omega** prior to conformer generation using the
  ``sparse`` mode.

    .. oe:source:: GPUOmega.cpp
       :language: c++
       :noindent:
       :frag:     SNIPPET-GPUOmega-sparse
       :caption:  Example of turning off GPU-Omega

    .. oe:source:: GPUOmega.py
       :language: python
       :noindent:
       :frag:     SNIPPET-GPUOmega-sparse
       :caption:  Example of turning off GPU-Omega

    ..  oe:language:: python

        :ref:`Full listing. <listing-GPUOmega.py>`

    .. oe:source:: GPUOmega.java
       :language: java
       :noindent:
       :frag:     SNIPPET-GPUOmega-sparse
       :caption:  Example of turning off GPU-Omega

* **GPU-Omega** uses the default :oe:constns:`OEFF::OEMMFFSheffieldFFType::MMFF94Smod_NOESTAT`
  force field. If attempting to use an alternative force field, conformer generation will
  fall back to the CPU. **GPU-Omega** is also incompatible with ``hydrogen sampling``, which is
  turned off in the default sampling mode. As a result, **GPU-Omega** is not compatible
  with the default settings of :oe:const:`OEConfGen::OEOmegaSampling::Dense` sampling mode. To take
  advantage of a GPU with ``dense`` sampling mode, set :oe:meth:`OEConfGen::OETorDriveOptions::SetForceField`
  to :oe:constns:`OEFF::OEMMFFSheffieldFFType::MMFF94Smod_NOESTAT`, and set 
  :oe:meth:`OEConfGen::OEMolBuilderOptions::SetSampleHydrogens` to *false*.

* The :oe:func:`OEConfGen::OEOmegaIsGPUReady` utility function is provided for detecting available GPUs
  on a system.

* The following code demonstrates how to query the system for an available GPU and then set the
  force field to default in order to use the GPU for ``dense`` mode conformer generation.

      .. oe:source:: GPUOmega.cpp
         :language: c++
         :noindent:
         :frag:      SNIPPET-GPUOmega-dense
         :caption:   Example of detecting a GPU and changing the force field for dense mode conformer generation

      .. oe:source:: GPUOmega.py
         :language: python
         :noindent:
         :frag:     SNIPPET-GPUOmega-dense
         :caption:  Example of detecting a GPU and changing the force field for dense mode conformer generation

      .. oe:source:: GPUOmega.java
         :language: java
         :noindent:
         :frag:     SNIPPET-GPUOmega-dense
         :caption:  Example of detecting a GPU and changing the force field for dense mode conformer generation

* **GPU-Omega** does **not** support the distance geometry method of torsion driving, and therefore
  is incompatible with :oe:const:`OEConfGen::OEMacrocycleOmega`.

.. caution::

  To use **GPU-Omega** with child processes, a new :ref:`OEOmega <OEConfGen_OEOmega>` object must be created for each child.
  If attempting to use the same instance of an :ref:`OEOmega <OEConfGen_OEOmega>` object in child processes, conformer
  generation will fall back to the CPU.
