
.. _section_oechem_releasenotes_204:

********************************************************************************
Version 2.0.4
********************************************************************************

OEChem 2.0.4
================================================================================

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

* The following API have been added to generate and use 2D ring dictionaries:

  * :ref:`OE2DRingDictionary <OEChem_OE2DRingDictionary>` class
  * :oe:func:`OEChem::OEIsValid2DRingDictionary` function
  * :oe:func:`OEChem::OEWrite2DRingDictionary` function
  * :oe:func:`OEChem::OEInit2DRingDictionary` function

  The following sections provide examples to generate and utilize user-defined
  2D ring dictionaries:

  * :ref:`section_example_oechem_createringdict`
  * :ref:`section_example_oechem_appendringdict`
  * :ref:`section_example_oechem_generate2D`

.. seealso::

   :ref:`ringdict2pdf<section_examples_summary_ringdict2pdf>` example in
   **OEDepict TK** will generate a multi-page PDF report of a 2D ring dictionary.

* 221 new ring templates have been added to the built-in ring dictionary.

  .. list-table:: **Example of the New 2D Ring Templates**
     :widths: 15 7

     * - **Pure Carbon Skeleton Ring Templates**
       - **Ring Templates with Specified CIS/Trans Bonds**

     * - .. image:: ../../oechemtk/images/releasenotes-2.0.4/toolkits-2015-Jun-CarbonSkeletonTemplates.*
       - .. image:: ../../oechemtk/images/releasenotes-2.0.4/toolkits-2015-Jun-CisTransTemplates.*


* :oe:const:`OEChem::OEIFlavor::MOL2::Forcefield` flavor has been added to the MOL2 reader.
  This allows atom names in the MOL2 file to be interpreted as chemical
  elements while not using the second character if capitalized; for example, CA and CD
  are both carbon instead of calcium and cadmium. This will help reading
  :oe:const:`OEChem::OEFormat::MOL2` files
  that contain forcefield information like partial charges.

* :oe:func:`OEChem::OEAddCustomFASTAResidue` now provides the ability to
  customize :oe:const:`OEChem::OEFormat::FASTA` input files with
  unnatural nucleic acids.
  :oe:const:`OEChem::OEIFlavor::FASTA::CustomResidues` flavor is used
  to activate the new feature.
  :oe:const:`OEChem::OEIFlavor::FASTA::EmbeddedSMILES` flavor has also been
  added to experiment with adding cyclizations to peptides using
  custom tethers. These features are currently considered
  experimental; please send feedback to support@eyesopen.com.

.. oe:language:: c++

   * :oe:func:`OEChem::OEReadMolFromString` and
     :oe:func:`OEChem::OEWriteMolToString` have been added.  These
     functions provide efficient molecule encoding to all the **OEChem**
     file formats. We anticipate significant performance improvements using
     these functions instead of the :oe:meth:`OEChem::oemolostream::openstring`
     method.

* :oe:const:`OEChem::OEOFlavor::SDF::UnsetBad2DStereo` and
  :oe:const:`OEChem::OEOFlavor::CDX::UnsetBad2DStereo`, new output
  flavors for SDF and CDX output formats, have been added.  These
  constants control behavior when generating 2D coordinates during
  output.  When used, the writer will set the stereo to "undefined" for
  any misleading stereochemistry that may result from layout
  limitations.

* :oe:func:`OEChem::OESubsetMol` has a new overload that supports the
  use of :ref:`OEAtomBondSet <OEChem_OEAtomBondSet>` input. This can offer
  significant performance improvements over the predicate overloads since
  a full molecule iteration can be avoided.

* :oe:meth:`OEChem::OEMolBase::ClearCoords` has been added to fully clear
  molecule coordinates, clear the dimension code, and reset perception flags.

* :oe:meth:`OEChem::OEMolDatabase::WriteMolecule` has been added to
  automatically extract a molecule from the database and write it to
  the :ref:`oemolostream <OEChem_oemolostream>`. This function is optimized for
  performance to simply move bytes around if the input
  :ref:`OEMolDatabase <OEChem_OEMolDatabase>` format and the output format match exactly.

* :oe:meth:`OEChem::OEMolDatabase::GetMoleculeString` has been added to allow
  direct access to the molecular record data.

* :oe:func:`OEChem::OEPRECompress` and
  :oe:func:`OEChem::OESweepRotorCompressHydrogens` have been added and
  documented to allow advanced users to start experimenting with
  perfect-rotor-encoding OEB files to achieve higher rates of conformer
  compression. This feature is currently only available to the C++
  toolkits.

* :oe:func:`OEChem::OEMDLGetValence` has been added to provide direct
  access to the MDL valence model. See the :ref:`section_valence_mdl`
  section for more information.


* The following free functions have been added for handling dummy atoms
  in forcefield calculations in special circumstances:

  - :oe:func:`OEFF::OESetForceFieldDummyAtom`
  - :oe:func:`OEFF::OEClearForceFieldDummyAtom`
  - :oe:func:`OEFF::OEClearForceFieldDummyAtoms`
  - :oe:func:`OEFF::OEIsForceFieldDummyAtom`

  Currently, dummy atoms are only allowed in **Szybki TK** for
  non-bonded interactions.

* :oe:func:`OEChem::OEAssignRadii` free function has been added to
  allow for a central entry point for any **OpenEye Toolkit** atomic
  radii assignment. This free function uses the
  :oe:constns:`OEChem::OERadiiType` namespace for choosing the type of
  radii to assign.

Major bug fixes
--------------------------------------------------------------------------------

* :oe:func:`OEChem::OEReadMolecule` will now correctly handle
  right-justified atomic symbols in MDL molfiles. These files are
  being generated by the RCSB PDB custom SDF file writer.

* :oe:func:`OEChem::OEPerceiveCIPStereo`, the Cahn-Ingold-Prelog
  stereochemistry perception algorithm, has been rewritten to solve
  the following issues:

  * Performance issues for large molecules have been resolved.

  * Incorrect chirality perception for certain isotopic molecules,
    detailed in the blog post
    `R or S? Let's Vote <http://nextmovesoftware.com/blog/2015/01/21/r-or-s-lets-vote/>`_,
    has been corrected.

  * Incorrect chirality perception for stereocenters with both
    a hydrogen and either a deuterium or tritium attached has been fixed.

  * Incorrect chirality perception for stereocenters with both a
    hydrogen and a \*atom (atomic number 0) has been fixed.

.. oe:language:: c++

  * :oe:meth:`OEChem::oemolistream::openstring` will now properly reset
    the state of the :ref:`oemolistream <OEChem_oemolistream>` to use the new data
    passed to :oe:meth:`OEChem::oemolistream::openstring` whenever
    :oe:meth:`OEChem::oemolistream::Setgz` was previously
    called. In earlier releases, :oe:meth:`OEChem::oemolistream::openstring`
    would only work the first time it was called; subsequent calls would
    fail to use the new data, even though the function was returning
    ``true`` as if it had succeeded.

* :oe:meth:`OEChem::oemolistream::Setgz` with a ``false`` argument
  called after a stream has finished reading molecules will no longer
  cause :oe:func:`OEChem::OEReadMolecule` to crash on subsequent
  calls. It will now return ``false`` to indicate that the stream has
  finished.

* :oe:meth:`OEChem::OEMolDatabase::Open` will now fail and throw a
  warning message if there is no disk space left for uncompressing
  compressed input files. In earlier releases, the operation would appear to
  succeed and lead to corrupted molecules past a certain
  point. Furthermore, the directory that :ref:`OEMolDatabase <OEChem_OEMolDatabase>`
  uses for temporary files can now be controlled through the ``TEMP``
  or ``TMP`` environment variables on Windows or the ``TMPDIR``
  environment variable on `Linux and OSX <http://pubs.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap08.html>`_.

* :ref:`OEMol <OEChem_OEMol>` will now work with the ``V3000`` file format
  much more reliably. This was accomplished by making sure that
  multi-conformer molecules can handle groups appropriately.  The
  :ref:`OEGroupBase <OEChem_OEGroupBase>` class is a container of atom and bond
  pointers inside an :ref:`OEMCMolBase <OEChem_OEMCMolBase>`.  The
  :ref:`OEGroupBase <OEChem_OEGroupBase>` class is currently used to store
  MDL-enhanced stereo information.  Each conformer of the multi-conformer
  molecule has its own separate container.  Now methods such as
  :oe:meth:`OEChem::OEMolBase::GetGroups` will provide access to the
  groups of the active conformation.


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

* :oe:const:`OEChem::OEFormat::OEB` format reading will no longer
  cause a rare crash when dealing with large amounts of SD data, PDB
  data, or bond integer types.

* :ref:`OEMatchBase <OEChem_OEMatchBase>` now checks parameters to the overloaded versions of
  the :oe:func:`OEChem::OESubsetMol` function to ensure that the given match corresponds
  to source and destination molecules.

* :oe:meth:`OEChem::OEMolBase::NewGroup` method signatures now take
  ``const std::vector`` of atom and/or bond pointers. Previously,
  these arguments were not ``const`` even though the vectors were not
  altered.

* :oe:func:`OEChem::OEReadMolecule` will now perform chirality
  perception for 0D MDL molfiles to ensure that
  :oe:meth:`OEChem::OEAtomBase::IsChiral` and
  :oe:meth:`OEChem::OEBondBase::IsChiral` are correct.

* :oe:func:`OEChem::OEGetAtomicNum` is now tolerant of leading spaces for the
  string argument passed in.

Java-specific changes
--------------------------------------------------------------------------------

* :ref:`OEBinaryIOHandlerBase <OESystem_OEBinaryIOHandlerBase>` had accidentally been
  removed from Java in the 2014.Oct release. This broke
  the older idiom for preserving rotor-offset compression in OEB files
  using :oe:func:`OEChem::OEInitDefaultHandler`. The preferred API is
  to now use :oe:func:`OEChem::OEPreserveRotCompress` directly on the
  molecule streams, avoiding the need to access the
  :ref:`OEBinaryIOHandlerBase <OESystem_OEBinaryIOHandlerBase>` internals entirely.

* The ``OEUnaryRoleSetPredicateFunc`` function was renamed to
  ``OEUnaryRoleSetBoolFunc`` for the sake of consistency.

* :ref:`OERoleSet <OESystem_OERoleSet>` predicates can now be created and
  customized in the same way as atom and bond predicates.
  :ref:`OERoleSet <OESystem_OERoleSet>` predicates are an important part of
  customizing the new **OEBio TK** :ref:`Splitting Macromolecular
  Complexes <section_split_mol_complex>` feature.

* :ref:`OERoles <OESystem_OERoles>` class has been added as a concrete implementation
  of the :ref:`OERoleSet <OESystem_OERoleSet>` abstract base class.

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

* :ref:`chapter_2D_coordinates` chapter has been added.

OEBio 2.0.4
================================================================================

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

* An API has been added for classifying and separating the various components of a
  macromolecular complex by their functional roles.
  See the :ref:`Splitting Macromolecular Complexes <section_split_mol_complex>`
  section for more information.

  * :oe:func:`OEBio::OESplitMolComplex` function
  * :oe:func:`OEBio::OEGetMolComplexComponents` function
  * :oe:func:`OEBio::OECountMolComplexSites` function
  * :ref:`OESplitMolComplexOptions <OEBio_OESplitMolComplexOptions>` class
  * :ref:`OEMolComplexCategorizer <OEBio_OEMolComplexCategorizer>` class
  * :ref:`OEResidueCategoryData <OEBio_OEResidueCategoryData>` class
  * :ref:`OEMolComplexFilter <OEBio_OEMolComplexFilter>` class

* :oe:func:`OEBio::OEGetResidues` function has been added to allow
  iteration over all unique :ref:`OEResidue <OEChem_OEResidue>` objects in
  an :ref:`OEMolBase <OEChem_OEMolBase>`.

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

* :ref:`chapter_protein_prep` chapter has been added to document the
  APIs for splitting macromolecular complexes into their components.

OESystem 2.0.4
================================================================================

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

* :oe:meth:`OEThrow.SetLevel <OESystem::OEErrorHandler::SetLevel>` and
  :oe:meth:`OEThrow.GetLevel <OESystem::OEErrorHandler::GetLevel>`
  race conditions should be largely alleviated
  now. :oe:meth:`OESystem::OEErrorHandler::SetLevel` and
  :oe:meth:`OESystem::OEErrorHandler::GetLevel` will now affect the
  error message level for the current thread only; all new threads
  launch with the default error level of
  :oe:const:`OESystem::OEErrorLevel::Default` (``Info`` or above).

  .. warning::

     Multi-threaded **OpenEye Toolkit** programs may need to be
     updated to allow the desired output to be sent to standard
     error. However, the previous behavior was race-condition prone
     and difficult to get correct.

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

* :ref:`OERandom <OESystem_OERandom>` constructor will no longer take an
  ``unsigned int`` as input. Previously, the ``unsigned int`` would be
  implicitly cast to ``bool`` and would control whether to time
  seed the constructor. However, most users actually intend to use an
  ``unsigned int`` as a random number seed meant for the
  :oe:meth:`OESystem::OERandom::Seed` method. This change should catch
  this common mistake at compile time.

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

* :ref:`OEMath Functions <chapter_math_functions>` chapter now
  contains more detailed descriptions of the functions.

* Documentation has been added for the following classes:

  - :ref:`OEBinaryIOHandlerBase <OESystem_OEBinaryIOHandlerBase>`
  - :ref:`OEBinaryIOHandler <OESystem_OEBinaryIOHandler>`
  - :ref:`OEBInitializer <OESystem_OEBInitializer>`
  - :ref:`OEBoundedBuffer <OESystem_OEBoundedBuffer>`
  - :ref:`OEOwnedPtr <OESystem_OEOwnedPtr>`
  - :ref:`OEProtectedBuffer <OESystem_OEProtectedBuffer>`
  - :ref:`OEUnboundedBuffer <OESystem_OEUnboundedBuffer>`

OEPlatform 2.0.4
================================================================================

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

* :oe:func:`OEPlatform::OEFileTempPath` will now use the directory
  specified by the ``TMPDIR`` environment variable on
  `Linux and OSX
  <http://pubs.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap08.html>`_. This
  allows the user to control where **OpenEye Toolkits** will create
  temporary files. This is especially useful since
  :ref:`OEMolDatabase <OEChem_OEMolDatabase>` can use a lot of temporary
  storage when dealing with compressed data files.

OEGrid 1.5.1
================================================================================

* Minor internal changes have been made.
