
OEChem TK 5.0.0
================================================================================

New Features
--------------------------------------------------------------------------------

* The following preliminary APIs have been added for monomer, HELM, and peptide
  support.

  **Classes:**

  * :oe:cls:`OEChem::OEMonomer` — represents a monomer in a monomer set.
  * :oe:cls:`OEChem::OEMonomerData` — stores the definition of a monomer.
  * :oe:cls:`OEChem::OEMonomerSet` — a collection of monomers.
  * :oe:cls:`OEChem::OEMonomerValidationResult` — stores the result of monomer data validation.
  * :oe:cls:`OEChem::OEHelmParsingResult` — stores the result of HELM parsing.
  * :oe:cls:`OEChem::OEHelmGenerationResult` — stores the result of HELM generation.
  * :oe:cls:`OEChem::OEHelmGenerationOptions` — gives options for HELM generation.

  **Predicates:**

  * :oe:cls:`OEChem::OEIsInMonomerCodeSet` — filters monomers by code set.
  * :oe:cls:`OEChem::OEHasPolymerType` — filters monomers by polymer type.
  * :oe:cls:`OEChem::OEHasMonomerType` — filters monomers by monomer type.
  * :oe:cls:`OEChem::OEHasAminoAcidType` — filters monomers by amino acid type.
  * :oe:cls:`OEChem::OEIsMonomerGroup` — identifies groups that store monomer information.
  * :oe:cls:`OEChem::OEHasMonomerGroup` — identifies groups that match a monomer group by code set and code.

  **Constants:**

  * :oe:constns:`OEChem::OEAminoAcidType` — amino acid type constants.
  * :oe:constns:`OEChem::OEPolymerType` — polymer type constants.
  * :oe:constns:`OEChem::OEMonomerType` — monomer type constants.
  * :oe:constns:`OEChem::OEMonomerValidationReturnCode` — monomer validation return codes.
  * :oe:constns:`OEChem::OEHelmParsingReturnCode` — HELM parsing return codes.
  * :oe:constns:`OEChem::OEHelmGenerationReturnCode` — HELM generation return codes.
  * :oe:const:`OEChem::OEGroupType::Monomer` — monomer group type constant.
  * :oe:const:`OEChem::OEProperty::Monomer` — monomer property type constant.


  **Monomer data and validation functions:**

  * :oe:func:`OEChem::OEIsValidMonomerData`
  * :oe:func:`OEChem::OEAminoAcidTypeToString`
  * :oe:func:`OEChem::OEPolymerTypeToString`
  * :oe:func:`OEChem::OEStringToPolymerType`
  * :oe:func:`OEChem::OEMonomerTypeToString`
  * :oe:func:`OEChem::OEStringToMonomerType`

  **Monomer set I/O functions:**

  * :oe:func:`OEChem::OEReadMonomerSet`
  * :oe:func:`OEChem::OEWriteMonomerSet`
  * :oe:func:`OEChem::OELoadStandardMonomerSet`
  * :oe:func:`OEChem::OELoadOpenEyeMonomerSet`

  **Monomer perception and detection functions:**

  * :oe:func:`OEChem::OEDetectMonomers`
  * :oe:func:`OEChem::OEGetPolymerType`
  * :oe:func:`OEChem::OEGetMonomerType`
  * :oe:func:`OEChem::OEGetAminoAcidType`
  * :oe:func:`OEChem::OEIsStandardMonomer`
  * :oe:func:`OEChem::OEGetStandardAnalog`
  * :oe:func:`OEChem::OECreatePeptideMonomerConnectionSmiles`
  * :oe:func:`OEChem::OEMonomerConnectionSmilesFromCXSmiles`
  * :oe:func:`OEChem::OEPerceivePeptideMonomerConnections`

  **HELM functions:**

  * :oe:func:`OEChem::OEHelmToMol`
  * :oe:func:`OEChem::OEMolToHelm`
  * :oe:func:`OEChem::OEGetHelmChainNames`
  * :oe:func:`OEChem::OEGetHelmMonomerCodes`

  **Peptide perception functions:**

  * :oe:func:`OEChem::OEIsPeptide`
  * :oe:func:`OEChem::OEPerceivePeptideBackbone`

* A new function, :oe:func:`OEChem::OEHasRadii`, has been added to check if
  a molecule has radii assigned to all atoms. The function takes an optional 
  boolean argument ``all`` (default: ``true``) to specify whether to check 
  for radii on every atom or whether to return early on the first atom without radii.

* More :oe:constns:`OEChem::OEIFlavor` constants have been added for better control of perception steps when reading mmCIF files.

Minor Bug Fixes
--------------------------------------------------------------------------------

* When generating a substructure search database with :oe:func:`OEChem::OECreateSubSearchDatabaseFile`,
  molecules with high graph complexity (such as https://www.rcsb.org/ligand/ZRW) are now
  skipped since they are unlikely to be useful for substructure searching and can cause 
  significant performance degradation during database generation.

* The stack size of threads used in the :oe:func:`OEChem::OECreateSubSearchDatabaseFile`
  function have been increased to avoid memory allocation issues when processing :file:`.oeb` files with large number of
  generic data.

* An issue has been fixed in :oe:func:`OEBio::OEGetTorsion` where residue perception was called
  on a const atom changing the underlying perception state of the molecule.
  The function now correctly returns an invalid value when the residue is not already perceived
  with a warning to perceive it.


Python-Specific Changes
--------------------------------------------------------------------------------

* The :oe:meth:`OEChem::OEMolBase::NewGroup` method raises :py:class:`TypeError` if
  invoked with an invalid argument type.

* The hashing function for OEResidue has been updated to work with 
  multicharacter chain IDs.


OEBio TK
================================================================================

New Features
--------------------------------------------------------------------------------

* The following preliminary APIs have been added to serializing and deserializing
  interaction hints into :file:`.oeb` files.

  * :oe:func:`OEBio::OEConstructInteractionHintContainer`
  * :oe:func:`OEBio::OEDeleteInteractionsHintSerializationData`
  * :oe:func:`OEBio::OEDeleteInteractionsHintSerializationIds`
  * :oe:func:`OEBio::OEHasInteractionHintSerializationIds`
  * :oe:func:`OEBio::OEHasInteractionsHintSerializationData`
  * :oe:func:`OEBio::OESerializeInteractionsHintContainer`
  * :oe:func:`OEBio::OESetInteractionsHintSerializationIds`

* The serialization API for interaction hints now supports
  :ref:`OEDesignUnit <OEBio_OEDesignUnit>` directly. The following functions
  have new overloads accepting an :oe:cls:`OEBio::OEDesignUnit`:

  * :oe:func:`OEBio::OEConstructInteractionHintContainer`
  * :oe:func:`OEBio::OEDeleteInteractionsHintSerializationData`
  * :oe:func:`OEBio::OEDeleteInteractionsHintSerializationIds`
  * :oe:func:`OEBio::OEHasInteractionsHintSerializationData`
  * :oe:func:`OEBio::OESetInteractionsHintSerializationIds`

* The :ref:`OEInteractionHintContainer <OEBio_OEInteractionHintContainer>` class
  now supports a new :ref:`constructor overload <OEBio_OEInteractionHintContainer_Constructors>` that accepts an
  :oe:cls:`OEBio::OEDesignUnit`, assembling the receptor from the design unit
  components and the ligand (if present) automatically.

* Intramolecular interaction perception is now supported for a single component
  (either ligand or protein) by passing an empty molecule for the other
  component to the
  :ref:`OEInteractionHintContainer <OEBio_OEInteractionHintContainer>`
  constructor. For example, passing an empty molecule as the ligand argument
  will perceive only intramolecular interactions within the protein, and
  vice versa. This also applies when using the
  :oe:cls:`OEBio::OEDesignUnit` constructor overload: if a design unit has
  site residues but no ligand, intramolecular receptor interactions are
  perceived automatically.

* The following new predicates have been added for finer-grained filtering of
  interaction hints:

  * :ref:`OEIsClashingHBondInteractionHint <OEBio_OEIsClashingHBondInteractionHint>`
    identifies clashing hydrogen bond interactions (i.e.,
    :oe:const:`OEBio::OEHBondInteractionHintType::ClashAcceptorAcceptor` and
    :oe:const:`OEBio::OEHBondInteractionHintType::ClashDonorDonor` types).

  * :ref:`OEIsUnpairedInteractionHint <OEBio_OEIsUnpairedInteractionHint>`
    identifies all unpaired interactions, including unpaired hydrogen bond
    donors/acceptors and unpaired salt-bridge charges.

  * :ref:`OEIsIntermolecularSaltBridgeInteractionHint <OEBio_OEIsIntermolecularSaltBridgeInteractionHint>`
    identifies intermolecular (ligand-protein) salt-bridge interactions.

  * :ref:`OEIsIntramolecularSaltBridgeInteractionHint <OEBio_OEIsIntramolecularSaltBridgeInteractionHint>`
    identifies intramolecular salt-bridge interactions within the ligand or protein.

  * :ref:`OEIsIntermolecularStackingInteractionHint <OEBio_OEIsIntermolecularStackingInteractionHint>`
    identifies intermolecular (ligand-protein) pi- and T-stacking interactions.

  * :ref:`OEIsIntramolecularStackingInteractionHint <OEBio_OEIsIntramolecularStackingInteractionHint>`
    identifies intramolecular pi- and T-stacking interactions within the ligand
    or protein.

  * :ref:`OEIsIntermolecularCationPiInteractionHint <OEBio_OEIsIntermolecularCationPiInteractionHint>`
    identifies intermolecular (ligand-protein) cation-pi interactions.

  * :ref:`OEIsIntramolecularCationPiInteractionHint <OEBio_OEIsIntramolecularCationPiInteractionHint>`
    identifies intramolecular cation-pi interactions within the ligand or protein.

  * :ref:`OEIsIntermolecularHalogenBondInteractionHint <OEBio_OEIsIntermolecularHalogenBondInteractionHint>`
    identifies intermolecular (ligand-protein) halogen bond interactions.

  * :ref:`OEIsIntramolecularHalogenBondInteractionHint <OEBio_OEIsIntramolecularHalogenBondInteractionHint>`
    identifies intramolecular halogen bond interactions within the ligand or protein.

* Intramolecular stacking and cation-pi interactions are now perceived and
  reported. The following new type constants have been added:

  * :oe:const:`OEBio::OEStackingInteractionHintType::IntramolecularLigandPi`
  * :oe:const:`OEBio::OEStackingInteractionHintType::IntramolecularLigandT`
  * :oe:const:`OEBio::OEStackingInteractionHintType::IntramolecularProteinPi`
  * :oe:const:`OEBio::OEStackingInteractionHintType::IntramolecularProteinT`
  * :oe:const:`OEBio::OECationPiInteractionHintType::IntramolecularLigand`
  * :oe:const:`OEBio::OECationPiInteractionHintType::IntramolecularProtein`

* A new option has been added to
  :ref:`OEPerceiveInteractionOptions <OEBio_OEPerceiveInteractionOptions>` to
  control the minimum stack offset required for a pi-stacking or T-stacking
  interaction to be reported:

  * :oe:meth:`OEBio::OEPerceiveInteractionOptions::SetMinStackOffset` /
    :oe:meth:`OEBio::OEPerceiveInteractionOptions::GetMinStackOffset`

  The stack offset is defined as
  :math:`\max(|\hat{c}\cdot\hat{n}_1|, |\hat{c}\cdot\hat{n}_2|)`, where
  :math:`\hat{c}` is the unit vector between the ring centers and
  :math:`\hat{n}_1` and :math:`\hat{n}_2` are the ring plane normals.
  This filter ensures that one ring sits above or below the other (i.e., a
  genuinely stacked arrangement) rather than side by side in the same plane.
  The default value is **0.5**.

* The following existing predicates have been updated to accept optional
  parameters that control whether intramolecular interactions and nonideal
  interactions are included in their results. All parameters default to ``True``
  to preserve backward-compatible behavior where interactions were previously
  returned without distinction:

  * :ref:`OEIsHBondInteractionHint <OEBio_OEIsHBondInteractionHint>` —
    new constructor ``OEIsHBondInteractionHint(bool includeIntra = true, bool includeNonIdeal = true)``

  * :ref:`OEIsIntermolecularHBondInteractionHint <OEBio_OEIsIntermolecularHBondInteractionHint>` —
    new constructor ``OEIsIntermolecularHBondInteractionHint(bool includeNonIdeal = true)``

  * :ref:`OEIsIntramolecularHBondInteractionHint <OEBio_OEIsIntramolecularHBondInteractionHint>` —
    new constructor ``OEIsIntramolecularHBondInteractionHint(bool includeNonIdeal = true)``

  * :ref:`OEIsChelatorInteractionHint <OEBio_OEIsChelatorInteractionHint>` —
    new constructor ``OEIsChelatorInteractionHint(bool includeIntra = true)``

  * :ref:`OEIsSaltBridgeInteractionHint <OEBio_OEIsSaltBridgeInteractionHint>` —
    new constructor ``OEIsSaltBridgeInteractionHint(bool includeIntra = true)``

  * :ref:`OEIsStackingInteractionHint <OEBio_OEIsStackingInteractionHint>` —
    new constructor ``OEIsStackingInteractionHint(bool includeIntra = true)``

  * :ref:`OEIsCationPiInteractionHint <OEBio_OEIsCationPiInteractionHint>` —
    new constructor ``OEIsCationPiInteractionHint(bool includeIntra = true)``

  * :ref:`OEIsHalogenBondInteractionHint <OEBio_OEIsHalogenBondInteractionHint>` —
    new constructor ``OEIsHalogenBondInteractionHint(bool includeIntra = true)``

* :ref:`OEDesignUnit <OEBio_OEDesignUnit>` now supports an additional
  ``SetSiteResidues`` overload that accepts
  ``std::vector<OEChem::OEResidue>``. The method validates that residues are
  present in the target, supports ligand coverage checks through ``threshold``
  and ``addBox``, supports optional component reassignment through
  ``rearrangeComponents``, and updates site-associated cofactors through
  ``siteSize``.

* A new overload to the function :oe:func:`OEChem::OEAssignRadii` that operates on
  :oe:cls:`OEBio::OEDesignUnit` has been added. The function
  takes a mask argument and radii types to assign specific radii to specified components.

* The :oe:cls:`OEBio::OEDesignUnit` now tracks the bond order of covalent bonds between components.

* The dictionaries used in :oe:cls:`OEBio::OEResidueCategoryData` have been updated.
  Specifically, `GCP` has been added as a cofactor. In addition, polymers were reclassified
  based on how often they appear as a standalone in the wwPDB, so they can be targeted as ligands, or,
  if they appear frequently as part of larger complexes, they can be treated as cofactors. 

Major Bug Fixes
--------------------------------------------------------------------------------

* An issue has been fixed where using :ref:`OEAltLocationFactory <OEBio_OEAltLocationFactory>`
  with the :oe:const:`OEBio::OEAltLocFactOption::TrustInputBonds` option
  could lead to incorrect perception of formal charges for atoms that had an atom with 
  multiple alternative locations bonded to it instead of proper reassignment of the implicit
  hydrogen count first.

* The :ref:`OEIsHBondInteractionHint <OEBio_OEIsHBondInteractionHint>` predicate
  previously returned ``true`` for clashing hydrogen bond interactions
  (:oe:const:`OEBio::OEHBondInteractionHintType::ClashAcceptorAcceptor` and
  :oe:const:`OEBio::OEHBondInteractionHintType::ClashDonorDonor`) and for
  unpaired hydrogen bond interactions
  (:oe:const:`OEBio::OEHBondInteractionHintType::UnpairedLigandDonor`,
  :oe:const:`OEBio::OEHBondInteractionHintType::UnpairedLigandAcceptor`,
  :oe:const:`OEBio::OEHBondInteractionHintType::UnpairedProteinDonor`, and
  :oe:const:`OEBio::OEHBondInteractionHintType::UnpairedProteinAcceptor`).
  These interaction types are now **excluded** from
  :ref:`OEIsHBondInteractionHint <OEBio_OEIsHBondInteractionHint>`, as they
  represent geometrically unfavorable or unpaired contacts rather than genuine
  hydrogen bonds. Use the new
  :ref:`OEIsClashingHBondInteractionHint <OEBio_OEIsClashingHBondInteractionHint>`
  predicate to retrieve clashing interactions, and the new
  :ref:`OEIsUnpairedInteractionHint <OEBio_OEIsUnpairedInteractionHint>` predicate
  for unpaired interactions (note: ``OEIsUnpairedInteractionHint`` also returns
  unpaired salt-bridge interactions).

* Similarly, :ref:`OEIsIntermolecularHBondInteractionHint <OEBio_OEIsIntermolecularHBondInteractionHint>`
  no longer includes clashing types, and
  :ref:`OEIsIntramolecularHBondInteractionHint <OEBio_OEIsIntramolecularHBondInteractionHint>`
  no longer includes unpaired types.

* The directionality of intramolecular hydrogen bond, salt bridge, and chelator interactions
  has been corrected:

  * Intramolecular hydrogen bond interactions now consistently
    report the donor as the begin fragment and the acceptor as the end fragment.
  * Intramolecular salt bridge interactions now consistently report the positive
    charge as the begin fragment and the negative charge as the end fragment.
  * Intramolecular chelator interactions now consistently report the metal as the
    begin fragment and the chelating atom as the end fragment.

* The :oe:meth:`OEBio::OEPerceiveInteractionOptions::GetMaxAtomPairDistance` has been updated
  to also include the MaxUnpairedDistance in the calculation of the maximum atom pair distance.

Minor Bug Fixes
--------------------------------------------------------------------------------

* :oe:func:`OEBio::OEGetActiveSiteInteractionHintTypes` no longer returns duplicate
  interaction hint types.

* An issue has been fixed where incorrect perception of stacking interactions would occur.
  The new feature mentioned above fixes this issue with an option to control the minimum stack offset
  required for a pi-stacking or T-stacking.

* An issue has been fixed where chelators were incorrectly perceived because of a missing angular term.

* An issue has been fixed where halogen interactions were incorrectly perceived because of a missing angular term.

* An issue has been fixed where, in the :oe:cls:`OEBio::OEIsCTerminalAtom` and :oe:cls:`OEBio::OEIsNTerminalAtom`
  methods, incorrect terminal atom identification could occur for nonstandard amino acid residues.

Python-Specific Changes
--------------------------------------------------------------------------------

* Python wrapping of :oe:meth:`OEBio::OEInteractionHintContainer::GetMolecules` methods has been fixed.

