

.. _section_omega_releasenotes_4006:

Omega TK 4.0.0.6
================================================================================

* :oe:meth:`OEConfGen::OEMolBuilder::Build` no longer enumerates specified nitrogen
  when :oe:meth:`OEConfGen::OEMolBuilderOptions::GetEnumNitrogen` is
  :oe:const:`OEConfGen::OENitrogenEnumeration::Unspecified`.

.. _section_omega_releasenotes_400:

Omega TK 4.0.0
================================================================================

As part of the integration of **OEToolkits** and **OEApplications** into a single
release, the version number of **Omega TK** has been upgraded to 4.0.0
to make it consistent with that of the **OMEGA** application.

New features
--------------------------------------------------------------------------------

* **GPU-Omega**, a GPU-accelerated implementation of the torsion driving algorithm,
  is now available. This will make use of any suitable Nvidia GPU on
  supported Linux platforms by default for ``classic`` mode runs. It is advised to read the
  :ref:`GPU-Omega <chapter_omegagpuomega>` section of the documentation to ensure that
  your system meets all the prerequisites and that availability is understood for the
  different sampling modes. On systems that do not meet the requirements,
  **GPU-Omega** will be disabled and fall back to the CPU.

  **GPU-Omega** introduces the following new APIs:

  * :oe:meth:`OEConfGen::OETorDriveOptions::GetUseGPU`
  * :oe:meth:`OEConfGen::OETorDriveOptions::SetUseGPU`
  * :oe:func:`OEConfGen::OEOmegaIsGPUReady`

* The following APIs have been promoted from preliminary API to stable API status:

  * :ref:`OEMacrocycleOmega <OEConfGen_OEMacrocycleOmega>`
  * :ref:`OEMacrocycleOmegaOptions <OEConfGen_OEMacrocycleOmegaOptions>`
  * :ref:`OEMacrocycleBuilder <OEConfGen_OEMacrocycleBuilder>`
  * :ref:`OEMacrocycleBuilderOptions <OEConfGen_OEMacrocycleBuilderOptions>`
  * :ref:`OEMolBuilder <OEConfGen_OEMolBuilder>`
  * :ref:`OEMolBuilderOptions <OEConfGen_OEMolBuilderOptions>`
  * :ref:`OEConformerBuilder <OEConfGen_OEConformerBuilder>`
  * :ref:`OEFragBuilder <OEConfGen_OEFragBuilder>`
  * :ref:`OEFragBuilderOptions <OEConfGen_OEFragBuilderOptions>`
  * :ref:`OEFragBuilderOptions <OEConfGen_OEFragBuilderOptions>`
  * :ref:`OETorDriver <OEConfGen_OETorDriver>`
  * :ref:`OETorDriveOptions <OEConfGen_OETorDriveOptions>`
  * :ref:`OEFragOptions <OEConfGen_OEFragOptions>`
  * :ref:`OERingFragOptions <OEConfGen_OERingFragOptions>`
  * :ref:`OEConfFixOptions <OEConfGen_OEConfFixOptions>`
  * :ref:`OEConfSlicer <OEConfGen_OEConfSlicer>`
  * :ref:`OESliceEnsembleOptions <OEConfGen_OESliceEnsembleOptions>`
  * :oe:constns:`OEConfGen::OEFragBuilderMode`
  * :oe:constns:`OEConfGen::OEOmegaReturnCode`
  * :oe:func:`OEConfGen::OEGetOmegaError`
  * :oe:func:`OEConfGen::OEIsMacrocycle`

* The :ref:`OEOmegaOptions <OEConfGen_OEOmegaOptions>` class has been simplified and now
  consists of multiple sub-options: :ref:`OEMolBuilderOptions <OEConfGen_OEMolBuilderOptions>`,
  :ref:`OETorDriveOptions <OEConfGen_OETorDriveOptions>`, :ref:`OESliceEnsembleOptions <OEConfGen_OESliceEnsembleOptions>`,
  and :ref:`OEConfFixOptions <OEConfGen_OEConfFixOptions>`.  The specific methods to set or
  get option values are now provided through these sub-option classes.

* A new abstract base class, :ref:`OEBuilderBase <OEConfGen_OEBuilderBase>`, has been added that
  contains the basic functionality of the builders that use a fragment library.

* The following new methods have been added to :ref:`OEConfFixOptions <OEConfGen_OEConfFixOptions>`:

  * :oe:meth:`OEConfGen::OEConfFixOptions::GetAtomExpr`
  * :oe:meth:`OEConfGen::OEConfFixOptions::SetAtomExpr`
  * :oe:meth:`OEConfGen::OEConfFixOptions::GetBondExpr`
  * :oe:meth:`OEConfGen::OEConfFixOptions::SetBondExpr`

* Two new methods, :oe:meth:`OEConfGen::OEFragBuilderOptions::SetForceField` and
  :oe:meth:`OEConfGen::OEFragBuilderOptions::GetForceField`, have been added
  to the :ref:`OEFragBuilderOptions <OEConfGen_OEFragBuilderOptions>` class.

* Two new methods, :oe:meth:`OEConfGen::OEMacrocycleBuilderOptions::SetRandomSeed` and
  :oe:meth:`OEConfGen::OEMacrocycleBuilderOptions::GetRandomSeed`, have been added
  to the :ref:`OEMacrocycleBuilderOptions <OEConfGen_OEMacrocycleBuilderOptions>` class.

* The following new methods have been added to :ref:`OEMacrocycleOmegaOptions <OEConfGen_OEMacrocycleOmegaOptions>`:

  * :oe:meth:`OEConfGen::OEMacrocycleOmegaOptions::GetEnergyWindow`
  * :oe:meth:`OEConfGen::OEMacrocycleOmegaOptions::SetEnergyWindow`
  * :oe:meth:`OEConfGen::OEMacrocycleOmegaOptions::GetMaxConfs`
  * :oe:meth:`OEConfGen::OEMacrocycleOmegaOptions::SetMaxConfs`

* A new method, :oe:meth:`OEConfGen::OEMolBuilder::Prep`, has been added to the
  :ref:`OEMolBuilder <OEConfGen_OEMolBuilder>` class to prepare molecules
  for building.

Minor bug fixes
--------------------------------------------------------------------------------

* The following methods now return ``bool``, instead of a ``void``:

  * :oe:meth:`OEConfGen::OEConfFixOptions::SetFixDeleteH`
  * :oe:meth:`OEConfGen::OEConfFixOptions::SetFixMaxMatch`
  * :oe:meth:`OEConfGen::OEConfFixOptions::SetFixMol`
  * :oe:meth:`OEConfGen::OEConfFixOptions::SetFixPredicate`
  * :oe:meth:`OEConfGen::OEConfFixOptions::SetFixRMS`
  * :oe:meth:`OEConfGen::OEConfFixOptions::SetFixSmarts`
  * :oe:meth:`OEConfGen::OEConfFixOptions::SetFixSubSearch`
  * :oe:meth:`OEConfGen::OEConfFixOptions::SetFixUniqueMatch`
  * :oe:meth:`OEConfGen::OEFragOptions::SetEnergyWindow`
  * :oe:meth:`OEConfGen::OEFragOptions::SetFragGen`
  * :oe:meth:`OEConfGen::OEFragOptions::SetFragKeep`
  * :oe:meth:`OEConfGen::OEFragOptions::SetRMS`
  * :oe:meth:`OEConfGen::OEFragOptions::SetTimeLimit`
  * :oe:meth:`OEConfGen::OEMacrocycleBuilderOptions::SetDielectricConst`
  * :oe:meth:`OEConfGen::OEMacrocycleBuilderOptions::SetRefTolerance`
  * :oe:meth:`OEConfGen::OEMacrocycleBuilderOptions::SetSkipRefinement`
  * :oe:meth:`OEConfGen::OEMacrocycleOmegaOptions::SetIterCycleSize`
  * :oe:meth:`OEConfGen::OEMacrocycleOmegaOptions::SetMaxIter`
  * :oe:meth:`OEConfGen::OEMolBuilderOptions::SetCanonOrder`
  * :oe:meth:`OEConfGen::OEMolBuilderOptions::SetEnumNitrogen`
  * :oe:meth:`OEConfGen::OEMolBuilderOptions::SetEnumRing`
  * :oe:meth:`OEConfGen::OEMolBuilderOptions::SetFromCT`
  * :oe:meth:`OEConfGen::OEMolBuilderOptions::SetSampleHydrogens`
  * :oe:meth:`OEConfGen::OEMolBuilderOptions::SetStrictAtomTypes`
  * :oe:meth:`OEConfGen::OERingFragOptions::SetStartFactor`
  * :oe:meth:`OEConfGen::OESliceEnsembleOptions::SetEnergyWindow`
  * :oe:meth:`OEConfGen::OESliceEnsembleOptions::SetEnergyRange`
  * :oe:meth:`OEConfGen::OESliceEnsembleOptions::SetMaxConfs`
  * :oe:meth:`OEConfGen::OESliceEnsembleOptions::SetMaxConfRange`
  * :oe:meth:`OEConfGen::OESliceEnsembleOptions::SetMaxTerminalHeavy`
  * :oe:meth:`OEConfGen::OESliceEnsembleOptions::SetRangeIncrement`
  * :oe:meth:`OEConfGen::OESliceEnsembleOptions::SetRMSThreshold`
  * :oe:meth:`OEConfGen::OESliceEnsembleOptions::SetRMSRange`
  * :oe:meth:`OEConfGen::OETorDriveOptions::SetCommentEnergy`
  * :oe:meth:`OEConfGen::OETorDriveOptions::SetMaxRotors`
  * :oe:meth:`OEConfGen::OETorDriveOptions::SetMaxSearchTime`
  * :oe:meth:`OEConfGen::OETorDriveOptions::SetRotorOffset`
  * :oe:meth:`OEConfGen::OETorDriveOptions::SetRotorPredicate`
  * :oe:meth:`OEConfGen::OETorDriveOptions::SetSDEnergy`
  * :oe:meth:`OEConfGen::OETorDriveOptions::SetTorLib`

* New arguments have been added to the :oe:meth:`OEConfGen::OEMacrocycleBuilder::Build` method
  for consistency with the other classes in **OMEGA**.

* The following preliminary APIs have been removed from the
  :ref:`OESliceEnsembleOptions <OEConfGen_OESliceEnsembleOptions>`
  class:

  * ``OESliceEnsembleOptions::SetEnergyThreshold``
  * ``OESliceEnsembleOptions::GetEnergyThreshold``
  * ``OESliceEnsembleOptions::SetSliceByEnergy``
  * ``OESliceEnsembleOptions::GetSliceByEnergy``

* Two methods, ``OETorDriver::SetForceField`` and ``OETorDriver::GetForceField``, that were
  preliminary APIs, have been removed from the :ref:`OETorDriver <OEConfGen_OETorDriver>` class.

* Two methods, ``OEMolBuilder::SetForceField`` and ``OEMolBuilder::GetForceField``, that were
  preliminary APIs, have been removed from the :ref:`OEMolBuilder <OEConfGen_OEMolBuilder>` class.

* Two methods, ``OEFragBuilder::SetForceField`` and ``OEFragBuilder::GetForceField``, that were
  preliminary APIs, have been removed from the :ref:`OEFragBuilder <OEConfGen_OEFragBuilder>` class.

* Two methods, ``OEMakeFragLib::SetForceField`` and ``OEMakeFragLib::GetForceField``, that were
  preliminary APIs, have been removed from the :ref:`OEMakeFragLib <OEConfGen_OEMakeFragLib>` class.

* Two methods, ``OEConfFixOptions::ClearFixFile`` and ``OEConfFixOptions::SetFixFile``, that were
  preliminary APIs, have been removed from the :ref:`OEConfFixOptions <OEConfGen_OEConfFixOptions>` class.
  Accordingly, :oe:meth:`OEConfGen::OEConfFixOptions::SetFixMol` has an overload that
  takes a molecule file as input.

* :oe:meth:`OEConfGen::OETorDriver::GenerateConfs` now errors out properly if the
  input molecule is not 3D.

* :oe:meth:`OEConfGen::OEOmega::Build` now properly de-duplicates the generated
  conformers in the case when :oe:meth:`MaxConfs<OEConfGen::OEOmegaOptions::SetMaxConfs>`
  is set to 0.

* :oe:meth:`OEConfGen::OEOmega::Build` no longer copies the molecule title to
  every conformer.

* :oe:func:`OEConfGen::OEGetOmegaError` now returns a value for each entry in the
  :oe:constns:`OEConfGen::OEOmegaReturnCode` namespace.

* :oe:meth:`OEConfGen::OEMakeFragLib::GenerateMissingFrags`
  and :oe:meth:`OEConfGen::OEFragBuilder::Build` now perform a de-duplication on the
  generated fragment conformers.

* :oe:meth:`OEConfGen::OEFragBuilder::Build` now returns an appropriate failure code
  if it fails due to lack of atom types.

* :oe:meth:`SampleHydrogens<OEConfGen::OEMolBuilderOptions::SetSampleHydrogens>` is now
  robust when the potential number of conformers is too high due to hydrogen sampling.

* Default values for the parameters in :ref:`OEMacrocycleOmegaOptions <OEConfGen_OEMacrocycleOmegaOptions>`
  are now consistent with their respective counterparts in the **OMEGA** command line
  application.

* :oe:func:`OEConfGen::OEIsMacrocycle` has been improved to better identify macrocycles
  when hetero atoms are involved.

Documentation changes
--------------------------------------------------------------------------------

* A :ref:`GPU-Omega <chapter_omegagpuomega>` chapter has been added to the documentation.

* **OMEGA** examples have been updated to reflect the latest changes for all supported
  languages.

General Notices
--------------------------------------------------------------------------------

* In the C++ toolkit, **GPU-Omega** is not available on RHEL8 or Ubuntu18 in this release.
