.. _section_oechem_releasenotes_200:

********************************************************************************
Version 2.0.0
********************************************************************************

OEChem 2.0.0
================================================================================

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

* :ref:`OEMolDatabase <OEChem_OEMolDatabase>` class added for providing fast random
  read-only access to all the file formats **OEChem** supports. Please
  see the new :ref:`Molecular Database Handling <chapter_moldatabase>` chapter
  of the documentation for a more thorough description.

.. warning::

   The meaning of the :file:`.smi` file extension has changed in
   OEChem 2.0. The :file:`.smi` file extension will now retain
   stereochemistry information. This could cause problems for systems
   that relied upon :file:`.smi` to strip away stereo chemistry.

* The following changes have been made to how OEChem defines the
  various flavors of SMILES (see images demonstrating these changes in
  :ref:`Table: SMILES File Formats <table_SMILES_changes>`):

  * The ``.smi``, :oe:const:`OEChem::OEFormat::SMI`, file format outputs
    :term:`Canonical isomeric SMILES`.

  * :oe:const:`OEChem::OEFormat::USM` file format added (with the
    :file:`.usm` file extension) that allows the generation of
    non-canonical, non-isomeric :term:`SMILES`, i.e., the OEChem 1.x
    definition of the :file:`.smi` file extension.

  * :oe:func:`OEChem::OEGetFormatString` returns more descriptive
    values for the various flavors of :term:`SMILES` regarding
    canonicalization and stereo information.

  * The default file format for molecule streams is now
    :oe:const:`OEChem::OEFormat::SMI` and is identical to the
    :oe:const:`OEChem::OEFormat::ISM` format.

  .. _table_SMILES_changes:

  .. list-table:: **SMILES File Formats**

     * - .. image:: ../../oechemtk/images/releasenotes-2.0.0/SmilesFormats-Version1_9_3.*
       - .. image:: ../../oechemtk/images/releasenotes-2.0.0/SmilesFormats-Version2_0_0.*

* :oe:const:`OEChem::OEFormat::CSV` file format added to **OEChem** for
  round-tripping molecules and SD data to other software packages that
  support the comma-separate-value, :file:`.csv`, file
  format. **OEChem** supports the :file:`.csv` file format that has
  largely become ubiquitous and is now standardized by `RFC 4180
  <http://tools.ietf.org/html/rfc4180>`_. The following APIs were
  added for handling CSV files in **OEChem**:

  - :oe:func:`OEChem::OEReadCSVFile`
  - :oe:func:`OEChem::OEWriteCSVFile`
  - :oe:func:`OEChem::OECreateCSVHeader`
  - :ref:`OECSVHeader <OEChem_OECSVHeader>`
  - :oe:meth:`OEChem::oemolstreambase::GetCSVHeader`
  - :oe:meth:`OEChem::oemolstreambase::ClearCSVHeader`

* Added automatic 2D coordinate generation to the following file formats when
  invoking the :oe:func:`OEChem::OEWriteMolecule` high-level molecule writer:

  * In case of the :oe:const:`OEChem::OEFormat::MDL` and the
    :oe:const:`OEChem::OEFormat::SDF` file formats,
    2D coordinates are generated if the molecule has no coordinates *i.e.*
    existing 2D or 3D coordinates will be left intact.

  * In case of the :oe:const:`OEChem::OEFormat::CDX` file format, 2D coordinates
    are generated if the molecule has no 2D coordinates.

  This default behavior can be turned off by using the
  :oe:const:`OEChem::OEOFlavor::MDL::Add2D`,
  :oe:const:`OEChem::OEOFlavor::SDF::Add2D` and
  :oe:const:`OEChem::OEOFlavor::CDX::Add2D` flags, respectively.

* :oe:func:`OEChem::OEGetFormatExtension` will now return the most
  common file extension as the first element in the comma separated
  list for the :oe:const:`OEChem::OEFormat::PDB`,
  :oe:const:`OEChem::OEFormat::SDF`, and
  :oe:const:`OEChem::OEFormat::RDF` file formats.

* :oe:func:`OEChem::OEGenerate2DCoordinates` added to assign 2D
  coordinates to the given molecule.

* :oe:meth:`OEChem::OEMatchBase::IsValid` and :oe:meth:`operator
  bool<OEChem::OEMatchBase::operator bool>` methods added.

* :ref:`OERoleSet <OESystem_OERoleSet>` abstract base class added as a mixin
  class to allow a class to contain a set of :ref:`OERole <OESystem_OERole>`
  objects for classification purposes. This is similar to how the
  :ref:`OEBase <OESystem_OEBase>` class provides associative data container
  behavior as "generic data". The following classes already derive
  from :ref:`OERoleSet <OESystem_OERoleSet>`:

  - :ref:`OEMatchBase <OEChem_OEMatchBase>`
  - :ref:`OEAtomBondSet <OEChem_OEAtomBondSet>`

  More classes across the toolkits may be added in the future as
  dictated by needs.

* :oe:meth:`OEChem::oemolstreambase::GetFileName` method added to all
  molecule streams to return the file name used to open the stream, if
  a file name was used.

* :oe:meth:`OEChem::OEMatchBase::IsValid` method added for determining
  whether the match contains any atoms or bonds.

* :oe:func:`OEChem::OEAssignZap7Radii` function added to assign radii
  from the ZAP7 set.

* :oe:func:`OEChem::OEParseSmilesOptions` class added for adding more
  complex :term:`SMILES` parsing options for the
  :oe:func:`OEChem::OEParseSmiles` function. This added the ability to
  make :oe:func:`OEChem::OEParseSmiles` quiet with regard to parsing
  failures through the
  :oe:meth:`OEChem::OEParseSmilesOptions::SetQuiet` method.

.. oe:language:: python

   * :ref:`OEGraphMol <OEChem_OEGraphMol>` and :ref:`OEMol <OEChem_OEMol>` are now
     picklable through the Python ``pickle.dumps`` and
     ``pickle.loads``.

   * :ref:`OEResidue <OEChem_OEResidue>` is now hashable in Python and thus
     usable as a dictionary key.

.. oe:language:: c++

   .. warning::

      ``OEChem::OEConfBase::operator C *`` has been removed
      from the API. C++ users who used this API for direct coordinate
      access or derived their own classes from
      :ref:`OEConfBase <OEChem_OEConfBase>` will need to change to the
      following different idiom.

   * ``OEChem::OEConfBase::operator C *`` has been removed in
     favor of the new :oe:meth:`OEChem::OEConfBase::GetCoordsPtr`
     methods. This allows implementations of
     :ref:`OEConfBase <OEChem_OEConfBase>` to use alternative data storage for
     coordinates, e.g., 64-bit ``double`` precision floating
     point. Users of :ref:`OEConfBase <OEChem_OEConfBase>` should not use
     :oe:meth:`OEChem::OEConfBase::GetCoordsPtr` directly, instead
     relying on the :ref:`OEConstCoords <OEChem_OEConstCoords>` and
     :ref:`OEMutableCoords <OEChem_OEMutableCoords>` convenience classes.

   * Due to the above change, the following code will now fail to compile:

     .. code-block:: c++

        OEMol mol;
        for (OEIter<OEConfBase> conf = mol.GetConfs(); conf; ++conf)
          mol.NewConf(*conf);

     This code was not doing what most programmers thought it was
     doing. It was actually implicitly casting the ``OEConfBase &``
     into a ``float *`` and then calling the version of ``NewConf``
     that takes a ``float`` pointer. Users should change their code to
     the following:

     .. code-block:: c++

        OEMol mol;
        for (OEIter<OEConfBase> conf = mol.GetConfs(); conf; ++conf)
          mol.NewConf(conf);

   * The following methods that rely on ``OEConfBaseT<float, 2>`` and
     ``OEConfBaseT<double, 3>`` template instatiations were removed and
     replaced with :ref:`OEMolBase <OEChem_OEMolBase>` versions:

     - :oe:meth:`OEChem::OETransBase::Transform`
     - :oe:meth:`OEChem::OETrans::Transform`

   .. note::

      This is part of a larger effort to migrate away from the
      ``OEChem::OEConfBaseT`` template class in favor a pure
      abstract :ref:`OEConfBase <OEChem_OEConfBase>` class to allow for
      conformer storage in formats other than 32-bit precision
      ``float``. This will only affect C++ users of the toolkit, even
      then, users who only used ``OEConfBase`` as a typedef should not
      be affected.



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

* The :oe:const:`OEChem::OEFormat::MDL` V3000 file format was unable to
  read multiple molecules from the same file if they were all in the
  V3000 format. Note, this did not affect the
  :oe:const:`OEChem::OEFormat::SDF` files containing V3000 as those
  files contain '$ $ $ $' to delimit separate molecule records.

* ``OEChem::OEReadHeader`` will no longer corrupt the stack by
  arbitrarily zeroing out bytes on the stack whenever no
  :ref:`OEHeader <OESystem_OEHeader>` record is found in the
  :oe:const:`OEChem::OEFormat::OEB` file.

* :oe:meth:`OEChem::OEMatch::AddPair` will no longer crash if
  :oe:meth:`OEChem::OEMatch::Clear` was previously called.

* :oe:meth:`OEChem::oemolthreadbase::PutMol` will now destroy the
  pointer passed to it if the underlying buffer returns ``false``,
  e.g., the buffer has already been closed.

* :oe:func:`OEChem::OEAddMols`, :oe:func:`OEChem::OESuppressHydrogens`,
  and :oe:func:`OEChem::OEPerceiveSymmetry` will no longer cause a
  stack overflow and crash when the molecule has a large number of
  atoms.

.. oe:language:: java

   - This fixed a non-deterministic Java JVM hotspot crashes.

.. oe:language:: java

   * Java performance optimized for functions that return arrays of
     :ref:`OEAtomBase <OEChem_OEAtomBase>` or :ref:`OEBondBase <OEChem_OEBondBase>` as
     output arguments, like :oe:func:`OEChem::OESubsetMol`.

.. oe:language:: python java csharp

   * A subtle memory and performance bug was fixed for the
     :ref:`OEMol <OEChem_OEMol>`, :ref:`OEGraphMol <OEChem_OEGraphMol>`, and
     :ref:`OEQMol <OEChem_OEQMol>` copy constructors. Every time a copy was
     made an extra layer of proxy object was created, causing memory
     consumption to increase, as well as making any subsequent use of
     that object slower.


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

* Removed unimplemented ``OEChem::OEFormat::TDT`` file format.

* Removed ``OEChem::OEFormat::BIN`` format after being
  deprecated for 10 years.

* :oe:func:`OEChem::OEMolToSmiles` no longer outputs the title of the
  molecule.

* If :oe:func:`OEChem::OE3DToAtomStereo` or
  :oe:func:`OEChem::OE3DToBondStereo` throws a warning message during a
  call to :oe:func:`OEChem::OEMolToSmiles`, the warning message will no
  longer erroneously say it is during a call to ``OEWriteMolecule``.

* :oe:func:`OEChem::OESetComment` and :oe:func:`OEChem::OEGetComment`
  have have been slightly optimized for speed. There is also a larger
  optimization for memory and file space in the :file:`.oeb`
  format. Previously, setting the comment to an empty string would
  write superfluous data to the :file:`.oeb` file.

* :oe:func:`OEChem::OECopySDData` and :oe:func:`OEChem::OECopyPDBData`
  will no longer increase the memory consumption of the destination
  molecule whenever the source molecule does not contain any
  data. This was causing :oe:const:`OEChem::OEFormat::PDB` files read
  into a :ref:`OEMCMolBase <OEChem_OEMCMolBase>` to use more memory than
  necessary.

* :oe:const:`OEChem::OEFormat::MOL2` parser will no longer create bonds
  with zero-order from "dummy bonds". Zero-order bonds cause problems
  for many **OEChem** algorithms like :oe:func:`OEChem::OEKekulize`.

* :oe:const:`OEChem::OEFormat::MOL2` parser will now properly ignore
  lines between molecule records that start with the pound sign,
  "#". Previously, these lines would cause **OEChem** to spew a lot of
  warnings and cause the parser to fail.


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

* The chapter about InChI failures has been removed since most of the
  InChI failures were fixed in the last release, **OEChem** 1.9.3 in
  2013.Oct.

* Release notes section re-organized to make the current release more
  prominent.

.. oe:language:: python

   * How to use :oe:func:`OEChem::OEDetermineRingSystems` from Python
     more thoroughly described.

.. oe:language:: c++ python

   * Added documentation and code example for
     :oe:func:`OEChem::OESmartsLexReplace`. The old function named
     ``SmartsLexReplace`` without the leading ``OE`` is considered
     deprecated and has been removed from the documentation.


OESystem 2.0.0
================================================================================

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

* Added support for handling the comma-separated-value, CSV, format
  specified by `RFC 4180 <http://tools.ietf.org/html/rfc4180>`_ with
  the following two free functions:

  - :oe:func:`OESystem::OEStringCSVJoin` for creating a CSV record
  - :oe:func:`OESystem::OEStringCSVTokenize` for parsing a CSV record

  The following low-level functions were added support
  CSV handling but can be ignored by most users:

  - :oe:func:`OESystem::OEStringCSVQuote` added
  - :oe:func:`OESystem::OEStringCollapseQuotes` added
  - :oe:func:`OESystem::OEStringStripQuotes` added

.. oe:language:: c++

   * :oe:func:`OESystem::OEStringJoin` now accepts a parameter to
     determine if the output string should end with the selected
     delimiter.

   * :oe:func:`OESystem::OEStringTokenizeQuoted` added a parameter for
     whether consecutive delimiters should be treated as a single
     delimiter. The default behavior is exactly the same as previous
     versions.

* :ref:`OEHalfFloat <OEPlatform_OEHalfFloat>` class added for storing floating
  point data as a 16-bit representation as specified by the `IEEE
  754-2008 standard
  <http://ieeexplore.ieee.org/xpl/articleDetails.jsp?reload=true&arnumber=4610935>`_
  to save on memory consumption and bandwidth.

.. oe:language:: c++

   - Collections of :ref:`OEHalfFloat <OEPlatform_OEHalfFloat>` objects,
     ``std::vector`` and arrays, can be attached to
     :ref:`OEBase <OESystem_OEBase>` objects and round-tripped through
     :file:`.oeb` files to save on disk size.

* The performance of reading plain-old-data attached to
  :ref:`OEBase <OESystem_OEBase>` objects from :file:`.oeb` files has been
  improved by about %10.

* :oe:func:`OESystem::OEErrorLevelToString` free function added.

* :oe:func:`OESystem::OEBFPosTEndian` added for allowing 64-bit
  integers to be round-tripped to binary formats regardless of machine
  endian-ness.

.. oe:language:: c++

  * ``OESystem::OEWriteData`` added to allow easily writing any
     data type as binary.

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

* :oe:constns:`OESystem::OEThrow` mutex handling has been
  migrated from :ref:`OEErrorHandler <OESystem_OEErrorHandler>` down a level into
  ``OESystem::OEErrorHandlerStreamImpl``. This fixes the following issues:

  - The mutex can now be properly released during a process exit like
    :oe:meth:`OESystem::OEErrorHandler::Fatal`.
  - A deadlock will no longer occur if the implementation of
    :oe:meth:`OESystem::OEErrorHandlerImplBase::Msg` needs to throw a
    message itself.
  - Allows alternative faster and more scalable implementations of
    :ref:`OEErrorHandlerImplBase <OESystem_OEErrorHandlerImplBase>` to be created and used
    with :oe:constns:`OESystem::OEThrow`.


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

* :oe:func:`OESystem::OEBitVectorNumWords` and
  :oe:func:`OESystem::OEBitVectorNumBytes` now take and return
  ``size_t``.

* ``OESystem::OEBinaryTagMaxLength`` constant added and set to
  1024, the maximum length of an explicit string tag in the
  :file:`.oeb` file format.

* :oe:func:`OESystem::OEStringTokenizeQuoted` will no longer treat a
  quote as the end quote of a field if it is escaped by another
  quote. :ref:`Table: OEStringTokenizeQuoted Change
  <table_OEStringTokenizeQuoted_changes>` demonstrates the change to
  support proper CSV parsing.

  .. _table_OEStringTokenizeQuoted_changes:

  .. list-table:: **OEStringTokenizeQuoted Change**

     * - OEChem 1.x
       - "foo"",bar",blah
       - ``"foo""``|``bar"``|``blah``
     * - OEChem 2.0+
       - "foo"",bar",blah
       - ``"foo"",bar"``|``blah``

* The size of :oe:func:`OESystem::OEBitVector` object has been
  increased from 12 bytes to 16 bytes on 64-bit machines. The size is
  still 8 bytes on a 32-bit machine.

.. oe:language:: python java csharp

   * The :ref:`OEErrorHandlerImplBase <OESystem_OEErrorHandlerImplBase>` copy constructor is
     now usable in Python, Java, and C#.

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

* :ref:`IsTrue <OESystem_IsTrue>` and :ref:`IsFalse <OESystem_IsFalse>` are
  deprecated and will be removed in ``OEChem 3.0``, please convert to
  using :ref:`OEIsTrue <OESystem_OEIsTrue>` and :ref:`OEIsFalse <OESystem_OEIsFalse>`.

* :ref:`OEUnaryTrue <OESystem_OEUnaryTrue>` and :ref:`OEUnaryFalse <OESystem_OEUnaryFalse>`
  documented as acceptable synonyms of :ref:`OEIsTrue <OESystem_OEIsTrue>` and
  :ref:`OEIsFalse <OESystem_OEIsFalse>`.

OEPlatform 2.0.0
================================================================================

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

.. oe:language:: python java csharp

   * :oe:func:`OEPlatform::OEAddLicenseFromHttp` added to license
     the current process with an OpenEye license file retrieved from a
     valid URL. The only supported URL schemes are HTTP and HTTPS. A
     reference implementation of a license server can be found at:
     (https://github.com/oess/HttpLicenseServer).

* :oe:func:`OEPlatform::OEAddLicenseData` function added to parse a
  string as if it is an OpenEye license file and then license the
  current process with it.

.. oe:language:: c++

   * :ref:`OELockCondition <OEPlatform_OELockCondition>` class added to provide a
     scoped lock on :ref:`OECondition <OEPlatform_OECondition>` objects.

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

* `OEPlatform::oeistream::size` was incorrectly being
  truncated to 32-bits on 32-bit machines. This resulted in incorrect
  file sizes being reported for files over 4 gigabytes in size on
  32-bit machines.

* `OEPlatform::oeifstream::tell` would return incorrect values
  if called after `OEPlatform::oeifstream::size` and after
  some bytes were already read from the stream.


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

* ``OEPlatform::OEMallocaPtr::GetPtr`` added to allow the object
  to be explicitly converted to a pointer type.

* :ref:`OEMutex <OEPlatform_OEMutex>` and :ref:`OETryMutex <OEPlatform_OETryMutex>`
  destructors will now destroy themselves on ``pthread`` based
  systems. Destroying mutexes is optional according to the ``pthread``
  standard, but helpful in debugging possible deadlocks.

* :ref:`OEMutex <OEPlatform_OEMutex>` and :ref:`OETryMutex <OEPlatform_OETryMutex>` no
  longer use ``gthreads``, instead using ``pthreads``, allowing for
  integration with non-GCC systems like libc++ on OSX.

OEGrid 1.4.5
================================================================================

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

* :oe:const:`OESystem::OEGridFileType::Ascii` file writer will no
  longer sometimes corrupt the stack and crash.

* When reading a CCP4 file, the standard deviation stored in the CCP4 header
  is now used to normalize the file.

* OENormalizeGrid now properly normalizes by sigma (not variance)

* Writing CCP4 maps now uses the original map statistics when possible.

* Rotated skew grids attached as generic data are now round-trippable when saved to OEB

* Fixed a crash when interpolating grids where the rotation matrix inverts the target grids
  bounding box

* MTZ files with more than 18 columns are now read properly

* Fixed a memory leak in :oe:meth:`OEBio::OESequenceAlignment`.

* The constructor for the predicate :ref:`OEHasResidueNumber <OEChem_OEHasResidueNumber>` now takes
  an int rather than an unsigned int because residue numbers can be negative.

