
.. _section_oechem_releasenotes_202:

********************************************************************************
Version 2.0.2
********************************************************************************

OEChem 2.0.2
================================================================================

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

* :oe:func:`OEChem::OEGenerate2DCoordinates` has an additional 550
  complex ring systems that it can use while laying out
  coordinates. Any structures that contain one of these complex ring
  systems will see dramatically better 2D coordinate generation. 

* ``OEChem::OEMCMolBaseT`` and ``OEChem::OEConfBaseT`` have
  been renamed to :ref:`OEMCMolBase <OEChem_OEMCMolBase>` and
  :ref:`OEConfBase <OEChem_OEConfBase>` respectively. This can only really have
  a technical effect on users of the direct C++ API. Python, Java, and
  C# users never saw a distinction between the template classes with
  the ``T`` suffix. For higher level language users, navigating the
  documentation and OEChem's type hierarchy should be greatly
  simplified.

* :oe:func:`OEChem::OEUncolorMol` is a new function for performing tunable
  uncoloring strategies for an input molecule.  Additional uncoloring
  strategies may be available in future versions.

* Significant performance improvement for
  :oe:meth:`OEChem::OEMolBase::GetAtoms`. Algorithms that do  
  molecular graph traversal should see a significant performance
  benefit. For example, :oe:func:`OEChem::OEShortestPath` was measured
  to be 25% faster. 

* :oe:func:`OEChem::OEPreserveRotCompress` added as a convenience
  function to ensure rotor-offset-compression is preserved when
  reading and writing molecules to OEB files. This function should be
  called on any :ref:`oemolistream <OEChem_oemolistream>` object that should
  preserve the rotor-offset-compression data needed to reproduce a
  smaller OEB file. 

* The performance of reading and writing rotor-offset-compression
  files has been improved, both when rotor-offset-compression data is
  preserved, and when it is not.

* Multiple lines of a CSV file format can be read into successive
  conformers of a :ref:`OEMCMolBase <OEChem_OEMCMolBase>` object. The SD data
  representing the data in the CSV file will be attached to each
  conformer.

* :ref:`OEAtomBondSet <OEChem_OEAtomBondSet>` added the following new methods to support the
  addition and removal of atom and bond object from the set:

  - :oe:meth:`OEChem::OEAtomBondSet::Add`
  - :oe:meth:`OEChem::OEAtomBondSet::ClearAtoms`
  - :oe:meth:`OEChem::OEAtomBondSet::ClearBonds`
  - :oe:meth:`OEChem::OEAtomBondSet::ClearAtomsAndBonds`
  - :oe:meth:`OEChem::OEAtomBondSet::Remove`
  - :oe:meth:`OEChem::OEAtomBondSet::RemoveAtom`
  - :oe:meth:`OEChem::OEAtomBondSet::RemoveBond`

  Adding of objects now verifies the membership of the object in the
  set prior to addition which will incur slightly more overhead than
  previous versions. This membership checking is in keeping with the
  spirit of uniqueness for a "set" implementation.

* :oe:func:`OEChem::OESubsetMol` has new overloads to support use of
  subsetting activities using the :ref:`OEAtomBondSet <OEChem_OEAtomBondSet>`
  object to define the subset.

* :oe:func:`OEChem::OEMDLPerceiveBondStereo` will cause
  :oe:func:`OEChem::OEReadMolecule` to produce fewer warning messages.
  :oe:func:`OEChem::OEMDLPerceiveBondStereo` was creating ambiguous
  stereo bond marks, additional attempts are now made to apply
  unambiguous stereo bond marks. In some cases, this may result in >1
  bond mark to a center to fulfill the requirements of the internal
  checking algorithm for validly marked centers.  Pathological
  geometries remain where no valid marks can unambiguously define the
  stereocenter.  For example, for some fused ring systems, the
  required (perhaps multiple) stereomarks would result in unpalatable
  marked stereocenters.

  .. hint::

     For some cases, :oe:func:`OEChem::OEMDLPerceiveBondStereo` will
     **not** be able to apply marks that will satisfy the
     :oe:func:`OEChem::OEReadMolecule` perception, and a warning
     message will be thrown by :oe:func:`OEChem::OEReadMolecule`
     indicating that these should be redrawn or have coordinates
     regenerated, e.g., adding an explicit hydrogen at the
     bridgehead(s) to carry a stereomark.

  .. note:: 

     :oe:func:`OEChem::OEWriteMolecule` automatically calls
     :oe:func:`OEChem::OEMDLPerceiveBondStereo` when writing to the
     :oe:const:`OEChem::OEFormat::MDL` and
     :oe:const:`OEChem::OEFormat::SDF` file formats.

* :oe:func:`OEChem::OEMDLHasIncorrectBondStereo` has been modified to
  check additional stereo environments for potential errors.  For example,
  both example structures below are now identified as having incorrect bond
  stereo marks where previously only the left structure was identified. 

  .. list-table::

     * - .. image:: ../../oechemtk/images/releasenotes-2.0.2/incorrect-stereo-A.*
       - .. image:: ../../oechemtk/images/releasenotes-2.0.2/incorrect-stereo-B.*


* :ref:`OEMol <OEChem_OEMol>` can now represent conformer coordinates in
  :ref:`OEHalfFloat <OEPlatform_OEHalfFloat>` (16-bit), ``double`` (64-bit), and
  ``long double`` (>=64-bit) precision. These molecule types can be
  accessed through the corresponding constants in the
  :oe:constns:`OEChem::OEMCMolType` namespace. 

  The following features were added to work in parallel with this new
  feature:
   
  - Reading and writing :ref:`OEHalfFloat <OEPlatform_OEHalfFloat>` (16-bit)
    precision conformers to the :oe:const:`OEChem::OEFormat::OEB` file
    format, including rotor-offset-compressed files. 
  - Reading and writing ``double`` (64-bit) precision conformers to
    the :oe:const:`OEChem::OEFormat::OEB` file format, including
    rotor-offset-compressed files.
  - Reading and writing ``double`` (64-bit) precision conformers to
    the :oe:const:`OEChem::OEFormat::XYZ` file format. By default, the
    XYZ writer will introspect the molecule type to determine how many
    significant digits to
    write. :oe:const:`OEChem::OEOFlavor::XYZ::SinglePrecision` and
    :oe:const:`OEChem::OEOFlavor::XYZ::DoublePrecision` can be used to force
    either 5 or 18 significant digits.
  - :oe:meth:`OEChem::OEMolBase::SetCoords`,
    :oe:meth:`OEChem::OEMolBase::GetCoords`, and
    :oe:meth:`OEChem::OEMCMolBase::NewConf` can now take coordinates in
    :ref:`OEHalfFloat <OEPlatform_OEHalfFloat>` and ``long double`` precision.
  - :oe:meth:`OEChem::OEConfBase::GetCoordsPtr` signature has been
    changed for better performance. Users should still prefer using
    :ref:`OEConstCoords <OEChem_OEConstCoords>` and :ref:`OEMutableCoords <OEChem_OEMutableCoords>`.
  - Conformer geometry operations will now preserve the precision of
    the input conformer coordinates.

  .. note::

     These alternative precision conformer implementations are not
     used by default. They require the user to explicitly specify a
     constant from the :oe:constns:`OEChem::OEMCMolType` namespace to
     the :ref:`OEMol <OEChem_OEMol>` constructor.

  .. warning:: 

     Older versions of OEChem, and thus many previously released
     OpenEye applications will not be able to read ``OEB`` files
     created from these alternative precision conformer
     molecules. Care should be taken to only pass these files to
     toolkits and applications that use at least the 2.0.2 version of
     OEChem. Note, this is not the default, the default is still to
     generate OEB files that can interoperate with older versions of
     OEChem.

.. oe:language:: java

   * New methods were added that utilize native Java collections interface:

     * :ref:`OEMolBase <OEChem_OEMolBase>` received three new methods that use java.util.List:

       - :oe:meth:`OEChem::OEMolBase::GetAtomList` returns a list of atoms
       - :oe:meth:`OEChem::OEMolBase::GetBondList` returns a list of bonds
       - :oe:meth:`OEChem::OEMolBase::GetGroupList` returns a list of groups
    
     * :ref:`OEMCMolBase <OEChem_OEMCMolBase>` received a new method that use java.util.List:
       - :oe:meth:`OEChem::OEMCMolBase::GetConfList` returns a list of conformers

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

* :oe:func:`OEChem::OEMDLStereoFromBondStereo` and
  :oe:func:`OEChem::OEMDLPerceiveBondStereo` will now generate
  consistent atom stereo when a wedge or hash bond occurs between
  atoms with an angle less than 180 degrees as shown in the following
  figure. This will make OEChem consistent with the official
  Accelrys definition of stereo in this case. As well as ensuring that
  SMILES can be round-tripped through an OEChem generated ``SDF``
  file that has had 2D coordinates automatically generated.

  .. image:: ../../oechemtk/images/releasenotes-2.0.2/AtomStereoProblem-toolkits2014_Oct.*

* :oe:func:`OEChem::OEMDLHasIncorrectBondStereo` had a major bug
  introduced in the 2014.Jun release. The bug was an incorrect array
  allocation and an out of bound access that resulted in
  nondeterministic processing of stereocenters and potential stack
  corruption. The 2014.Jun release should not be used for the
  :oe:func:`OEChem::OEMDLHasIncorrectBondStereo` function.

* :oe:func:`OEChem::OEWriteMolecule` will no longer improperly flip
  bond stereochemistry of complex macro-cycles when writing to
  :oe:const:`OEChem::OEFormat::MDL`, :oe:const:`OEChem::OEFormat::SDF`,
  or :oe:const:`OEChem::OEFormat::CDX` file formats. This was caused by
  the addition of automatically generating 2D coordinates when writing
  to these file formats in OEChem 2.0.0, the 2014.Feb release. In
  cases when the generated 2D coordinates are inconsistent with the
  cis/trans bond stereo configuration of the molecule, the coordinates
  will be zeroed out, i.e., the molecule will be written with no
  coordinates.  This can occur when generating 2D coordinates for a
  molecule that contains a macro-cycle with specified cis/trans stereo
  bond configuration like the following:

  .. image:: ../../oechemtk/images/releasenotes-2.0.2/BondStereoProblem-toolkits2014_Oct.*

* Writing to the :oe:const:`OEChem::OEFormat::SDF` and
  :oe:const:`OEChem::OEFormat::MDL` file formats will no longer
  improperly promote structures with relative stereochemistry to
  absolute stereochemistry in some cases. This case was when an input
  structure had atom stereomarks and a molecule chiral flag of '0'
  (i.e. relative stereochemistry) erroneously causing a promotion of
  relative stereochemistry to absolute stereochemistry on export to
  :oe:const:`OEChem::OEFormat::SDF` or
  :oe:const:`OEChem::OEFormat::MDL`.  This change only affects
  structures that originate from the V2000 and V3000 molfile formats
  without 3D coordinates. Structures from SMILES and other formats 
  don't represent relative stereochemistry, therefore, those formats
  will still only translate absolute stereochemistry.

* :oe:meth:`OEChem::OEMolDatabase::GetTitle` would sometimes return an
  empty title for multi-conformer OEB files that had their titles
  stored on the conformer. :oe:meth:`OEChem::OEMolDatabase::GetTitle`
  will now recognize this case and use the title from the first
  conformer if the top-level :ref:`OEMCMolBase <OEChem_OEMCMolBase>` does not
  have a title.

* Rotor-offset-compressed OEB files created on big-endian machines
  should now be readable on little-endian machines again. This bug was
  introduced in the 2011.1 release, the OEChem 1.7.5 release. The only
  big-endian architecture supported since then was PowerPC, and that
  support was dropped due to lack of usage. 

* :oe:func:`OEChem::OEGetDistance2` that takes a
  :ref:`OEConfBase <OEChem_OEConfBase>` will now return the square of the
  distance instead of the distance as it should. This bug was
  introduced in 2014.Feb, the OEChem 2.0.0 release.
  OEGetDistance2 functions that take arguments other than OEConfBase, e.g,
  OEMolBase, never had a bug introduced and will continue to return the
  square of the distance between the two atoms.

* :oe:func:`OEChem::OECreateInChI` will no longer crash and instead
  throw a warning when the InChI library returns an empty string.

* :oe:meth:`OEChem::OEConfBase::GetTitle` will be preferred over the
  :oe:meth:`OEChem::OEMolBase::GetTitle` when writing multi-conformer
  :ref:`OEMCMolBase <OEChem_OEMCMolBase>` molecules out to file formats that
  support titles. Previously, users were required to set the
  :ref:`OEMCMolBase <OEChem_OEMCMolBase>` title to an empty string,
  ``mol.SetTitle("")``, to achieve this behavior. This code will
  continue to work, but is no longer necessary to get the more specific
  conformer titles to be written out. ``OEB`` files will continue to
  write out both titles.

* :ref:`OEConstCoords <OEChem_OEConstCoords>` and :ref:`OEMutableCoords <OEChem_OEMutableCoords>`
  will no longer crash when given an empty molecule. 

.. oe:language:: python

   * The Python global interpreter lock is now handled properly by
     the following methods:

     - :oe:meth:`OEChem::oemolistream::openstring`
     - :oe:meth:`OEChem::oemolostream::GetString`
     - :oe:meth:`OEChem::oemolithread::openstring`
     - :oe:meth:`OEChem::oemolthreadbase::GetMol`
     - :oe:meth:`OEChem::oemolthreadbase::PeekMol`
     - :oe:meth:`OEChem::oemolthreadbase::PutMol`
     - :oe:meth:`OEChem::oemolothread::GetString`

     A race-condition was introduced in the previous release,
     2014.Jun, when Python 3 support was added. This race condition
     would occur when using any of the above methods in a
     multi-threaded environment.


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

* :oe:func:`OEChem::OE3DToAtomStereo`, for the perception of atom
  stereo from 3D coordinates, depends on the following properties:
  :oe:const:`OEChem::OEPerceived::RingAtomsAndBonds`,
  :oe:const:`OEChem::OEPerceived::Aromaticity`, and
  :oe:const:`OEChem::OEPerceived::Chiral`. If any of these properties
  are un-set when calling :oe:func:`OEChem::OE3DToAtomStereo`, they
  will be automatically reperceived before calculating the atom stereo
  properties.

* :oe:func:`OEChem::OE3DToBondStereo`, for the perception of bond
  stereo from 3D coordinates, depends on the following properties:
  :oe:const:`OEChem::OEPerceived::RingAtomsAndBonds`,
  :oe:const:`OEChem::OEPerceived::Aromaticity`, and
  :oe:const:`OEChem::OEPerceived::Chiral`. If any of these properties
  are un-set when calling :oe:func:`OEChem::OE3DToBondStereo`, they
  will be automatically reperceived before calculating the bond stereo
  properties.

* :oe:const:`OEChem::OEOFlavor::ISM::ExtBonds` will no longer be used
  when generating SMILES with :oe:func:`OEChem::OEMolToSmiles`.  This
  will cause :oe:func:`OEChem::OEMolToSmiles` to generate the same
  :term:`canonical isomeric SMILES` as when writing into an
  :oe:const:`OEChem::OEFormat::ISM` file format.

* ``OEChem::OEMCMolType::Torsion`` and
  ``OEChem::OEMCMolType::Rotation`` constants have been removed.

* :oe:func:`OEChem::OEInitHandler` called on the options specified by
  :oe:func:`OEChem::OEBDefaultOpts` will now initialize the handler to
  the exact same set of handlers as
  :oe:func:`OEChem::OEInitDefaultHandler`. The noticeable difference
  between the two was that :oe:func:`OEChem::OEInitHandler` would
  inadvertently turn on writing out the
  :oe:meth:`OEChem::OEBondBase::GetIntType` field, resulting in larger
  file sizes. :oe:meth:`OEChem::OEBondBase::GetIntType` was also turned
  on for the :oe:func:`OEChem::OEBRotCompressOpts` options as
  well. :oe:meth:`OEChem::OEBondBase::GetIntType` will now only be
  turned on by the :oe:func:`OEChem::OEBAtomIntTypeOpts` options. 

* :oe:const:`OEChem::OEMolBaseType::OEMiniMol` will now copy
  coordinates of other molecule implementations during copy
  construction.

* :ref:`OEMCMolBase <OEChem_OEMCMolBase>` read through
  :ref:`OEConfTestBase <OEChem_OEConfTestBase>` from non-SDF file formats should
  have a slightly smaller memory footprint. The ``MDLParity`` flag was
  always being stored in generic data, regardless of whether the
  molecule had the property or not.

* :oe:func:`OEChem::OEWriteMolecule` will no longer change the active
  conformer of an :ref:`OEMCMolBase <OEChem_OEMCMolBase>` while writing to file
  formats that do not support multi-conformer molecules like SDF and
  MOL2.

* :oe:func:`OEChem::OEWriteConstMolecule` will no longer ignore the
  flavors specified by the :ref:`oemolostream <OEChem_oemolostream>` for the
  :oe:const:`OEChem::OEFormat::XYZ` format.

* Warning message about an invalid format used with
  :oe:func:`OEChem::OEReadMolecule` was previously saying there was a
  problem with :oe:func:`OEChem::OEWriteMolecule`. This was incorrect,
  and the message now states "OEReadMolecule" instead. 

* Molecules read through :oe:meth:`OEChem::OEMolDatabase::GetMolecule`
  will no longer have their indices written to the OEB file
  format. This was just causing file size bloat and possibly confusing
  behavior with :oe:func:`OEChem::OEHasMolDBIdx` when the molecule was
  written and then read again from OEB through an
  :ref:`oemolistream <OEChem_oemolistream>`.

* :oe:meth:`OEChem::OEMolDatabase::GetTitle` fixed for PDB files that
  include data beyond the 72nd column. 

* Some redundant information is removed from OEB files written from
  :ref:`OEMCMolBase <OEChem_OEMCMolBase>` objects. This should make OEB files the
  exact same size when round-tripping molecules now instead of
  becoming slightly larger.

* :oe:const:`OEChem::OEFormat::SDF` and :oe:const:`OEChem::OEFormat::MDL` 
  file formats no longer support the long deprecated CPSS reaction
  fields. More deprecated atom and bond fields in the V2000 molfile format
  continue to be exported but will be removed entirely in future
  versions.

* :oe:func:`OEChem::OEMDLSetParity` added to allow
  explicitly setting the chiral flag status.  This was added for
  symmetry with :oe:func:`OEChem::OEMDLGetParity` and to allow explicit
  control of the exported chiral flag state by the user.

* :term:`SMILES` containing explicit hydrogens in stereo
  configurations were being non-optimally depicted. :term:`SMILES`
  parsing will now set the reaction role
  (:oe:meth:`OEChem::OEAtomBase::SetRxnRole`) of stereo explicit
  hydrogens.

* :oe:meth:`OEChem::OEMCMolBase::NewConf` will now return a ``NULL``
  :ref:`OEConfBase <OEChem_OEConfBase>` pointer instead of crashing when passed a
  ``NULL`` coordinates pointer.

Documentation fixes
--------------------------------------------------------------------------------

* :oe:constns:`OEChem::OEMolBaseType` is now documented. 

* :oe:constns:`OEChem::OEOFlavor::XYZ` is now documented. 

* All OpenEye code examples will now prefer to use
  :oe:func:`OEChem::OEMolToSmiles` and :oe:func:`OEChem::OESmilesToMol`
  instead of the ``OECreate*SmiString`` and ``OEParseSmiles``
  functions.

OEBio 2.0.2
================================================================================

* Minor internal improvements. 

OESystem 2.0.2
================================================================================

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

* Small performance improvements when writing generic data to OEB files. 

* :oe:func:`OESystem::OEGetHostEndian` and
  :oe:func:`OESystem::OEGetHostEndian` added to make template
  programming generic binary readers and writers easier.

* :oe:func:`OEMath::OEGeom3DAllZero` added to determine whether an
  array of floating point numbers is all zero.

* Many ``OEMath::OEGeom`` functions can now automatically up-cast
  :ref:`OEHalfFloat <OEPlatform_OEHalfFloat>` to float during their operation
  making working with :ref:`OEHalfFloat <OEPlatform_OEHalfFloat>` more seamless
  and requiring less temporary arrays.

* :oe:func:`OEMath::OEGeom3DReflect` added to reflect coordinates
  around any given axis.

* :oe:func:`OESystem::OECopyArray` should now be significantly faster
  for ``long double`` data arrays.

Documentation fixes
--------------------------------------------------------------------------------

* :oe:meth:`OESystem::OEBitVector::ToHexString` more thoroughly explained. 

* :ref:`OEBitVector <OESystem_OEBitVector>` documentation table was malformed.

OEPlatform 2.0.2
================================================================================

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

* :oe:meth:`OEPlatform::OEThread::Start` now returns a boolean value to
  indicate whether thread creation has failed. 

* :ref:`OEHalfFloat <OEPlatform_OEHalfFloat>` can now interconvert with
  ``double`` and ``long double`` more easily.

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

* :oe:func:`OEPlatform::OEFileRandomName` will now throw a warning that
  it is deprecated and will be removed in a future release. It is
  very dangerous and prone to race conditions.

* :ref:`OEMutex <OEPlatform_OEMutex>` data members are no longer exposed as
  ``public`` access on Windows.

Documentation fixes
--------------------------------------------------------------------------------

* :ref:`OEThread <OEPlatform_OEThread>` is now documented.


OEGrid 1.4.7
================================================================================

* Minor internal improvements. 
